Merge pull request #69 from madhura68/docs/runbook-agent-flow-pitfalls

docs(runbook): agent-flow open issues & decision log
2026-05-03 20:38:20 +02:00 · 2026-05-03 20:38:20 +02:00 · d8e6a68d69
commit d8e6a68d69
parent 0ee03c6b72 8d6bdef57e
3 changed files with 205 additions and 0 deletions
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@ -17,6 +17,7 @@ Auto-generated on 2026-05-03 from front-matter and headings.
 | 0006 | [ADR-0006: Demo-user write protection enforced in three layers](./adr/0006-demo-user-three-layer-policy.md) | accepted |
 | 0007 | [ADR-0007: Agent ↔ user question channel via persistent table + LISTEN/NOTIFY](./adr/0007-claude-question-channel-design.md) | accepted |
 | 0008 | [ADR-0008: Agent instructions in CLAUDE.md + topical runbooks](./adr/0008-agent-instructions-in-claude-md.md) | accepted |
+| 0010 | [ADR-0010: Eén product = één repo; cross-product planning vereist (later) een Initiative-laag](./adr/0010-product-per-repo-cross-product-planning.md) | accepted |

 ## Specifications

@ -97,6 +98,7 @@ Auto-generated on 2026-05-03 from front-matter and headings.
 | [DevPlanner — Product Backlog](./product-backlog.md) | `product-backlog.md` | active | 2026-05-03 |
 | [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 |
 | [Branch, PR & Commit Strategy](./runbooks/branch-and-commit.md) | `runbooks/branch-and-commit.md` | active | 2026-05-03 |
 | [Vercel Deployment](./runbooks/deploy-vercel.md) | `runbooks/deploy-vercel.md` | active | 2026-05-03 |
 | [MCP Integration — Scrum4Me Tools](./runbooks/mcp-integration.md) | `runbooks/mcp-integration.md` | active | 2026-05-03 |
--- a/docs/adr/0010-product-per-repo-cross-product-planning.md
+++ b/docs/adr/0010-product-per-repo-cross-product-planning.md
@ -0,0 +1,120 @@
+---
+status: accepted
+date: 2026-05-03
+decision-makers: Janpeter Visser
+consulted: Claude (planning agent)
+informed: alle Scrum4Me-gebruikers die met meerdere repos werken
+---
+
+# ADR-0010: Eén product = één repo; cross-product planning vereist (later) een Initiative-laag
+
+## Context and Problem Statement
+
+Een feature kan meerdere repositories raken — bv. de "agent merge-policy"-feature
+heeft tegelijk werk nodig in `Scrum4Me` (schema, server actions, UI) én in
+`scrum4me-mcp` (twee nieuwe MCP-tools). Het Scrum4Me-datamodel kent op dit
+moment één `repo_url` per `Product`, en stories hangen aan één PBI dat aan één
+product hangt. Hoe modelleren we werk dat structureel meerdere repos raakt?
+
+## Decision Drivers
+
+- Per-repo PR-volgorde en deploy-pipeline blijft simpel (1 PR = 1 repo).
+- Auditbaarheid: de link tussen "wat is gemerged" en "in welke repo" moet
+  triviaal te leggen zijn.
+- Het datamodel moet niet de complexiteit van een feature dragen die in 80% van
+  de gevallen toch single-repo is.
+- Plannen wel kunnen overspannen: een idee kan zonder fricted tegelijk taken
+  in twee repo's beschrijven.
+
+## Considered Options
+
+- **A. Eén product = één repo, plan-overspanning via duplicate-PBI per product.**
+  Een feature die twee repos raakt wordt als twee PBIs vastgelegd (één in elk
+  product), met handmatige verwijzing tussen de twee in de description.
+- **B. Multi-repo per product (`Product.repo_urls: String[]`).**
+  Eén product representeert een logisch "systeem" en heeft N repo's; PBIs en
+  stories blijven onder dat product.
+- **C. Initiative-laag boven PBI**, product-onafhankelijk; een Initiative bundelt
+  PBIs uit verschillende producten onder één plan.
+
+## Decision Outcome
+
+**Gekozen: optie A — voor nu**, met optie C als geïdentificeerde toekomstige
+uitbreiding zodra cross-repo werk regelmatig genoeg voorkomt.
+
+Rationale: optie B vermengt het datamodel rond een conceptueel troebele eenheid
+("product = systeem" vs. "product = repo") en breekt de 1:1-aanname in
+batch-enqueue, PR-gating en CI-flow. Optie C is structureel het juiste antwoord,
+maar verdient een eigen feature-traject (datamodel, UI, gating-semantiek per
+initiative) en wordt nu niet bevroren in een ad-hoc implementatie.
+
+### Consequences
+
+- Goed, omdat: per-repo flow simpel blijft (1 product = 1 repo = 1 PR-stack);
+  bestaande gating-logica (`pr_url`/`pr_merged_at` op PBI, sequentiële PBI's)
+  werkt zonder aanpassing.
+- Goed, omdat: cross-repo werk wordt expliciet zichtbaar als gespiegelde PBIs
+  in beide producten — geen verborgen koppelingen.
+- Slecht, omdat: voor cross-repo features moet een mens nu zelf twee PBIs
+  aanmaken en de afhankelijkheidsvolgorde tussen ze (bv. "MCP eerst, Scrum4Me
+  daarna") in de descriptions documenteren. Plan-drift tussen de twee PBIs is
+  een reëel risico.
+- Slecht, omdat: er komt geen "één klik = één feature klaar" flow voor
+  cross-repo werk; de PB-owner moet over twee producten heen schedulen en
+  mergen.
+
+### Confirmation
+
+Bevestiging dat deze ADR effectief is:
+
+1. Producten in Scrum4Me hebben elk precies één `repo_url`. Geen
+   schema-wijziging die `repo_urls` introduceert.
+2. PBIs voor cross-repo werk verwijzen in hun description expliciet naar de
+   spiegel-PBI in het andere product (id-link).
+3. Er staat een open backlog-item `Cross-product planning via Initiative-laag`
+   in product Scrum4Me als trigger om optie C te realiseren wanneer de pijn
+   van duplicatie te groot wordt.
+
+## Pros and Cons of the Options
+
+### A. Eén product = één repo, duplicate-PBI
+
+- Goed: minimaal datamodel-veranderingen.
+- Goed: PR-flow, batch-gating, deploy-pijplijn blijven 1:1 met repo.
+- Goed: per-product permissies en token-scoping blijven simpel.
+- Neutraal: cross-product werk vereist twee PBIs (zichtbaar werk, niet verborgen).
+- Slecht: dubbel onderhoud aan plan-tekst; risico op divergentie.
+
+### B. Multi-repo per product
+
+- Goed: één plek voor alles wat bij een "systeem" hoort.
+- Slecht: PR-gating per PBI moet plotseling N repos tegelijk modelleren.
+- Slecht: deploy-volgorde (eerst MCP, dan Scrum4Me) zit niet in het datamodel
+  → ad-hoc encoded in description of CI.
+- Slecht: vervaagt wat een "product" is — repo-technisch of business-technisch.
+
+### C. Initiative-laag boven PBI
+
+- Goed: structureel correct — werk dat de scope van één product overstijgt
+  krijgt zijn eigen niveau.
+- Goed: per-product gating en flow blijven simpel; alleen de Initiative
+  orkestreert.
+- Slecht: feature op zich (UI, datamodel, gating-semantiek per initiative,
+  velocity-rapportage) — significante investering vóór de eerste praktische
+  payoff.
+- Slecht: introduceert een vierde hiërarchielaag (Initiative → PBI → Story →
+  Task), met UI-druk om die zichtbaar te maken.
+
+## More Information
+
+- Verwante PBIs:
+  - Scrum4Me product, PBI `Agent merge-policy: geen auto-merge, sequentieel per
+    PBI` (id `cmoppwpwu000evt17ev2c4oo4`) — gebruikt deze ADR als grondvest voor
+    de gating per single-repo PR.
+  - scrum4me-mcp product, PBI `MCP: set_pbi_pr & mark_pbi_pr_merged voor
+    sequentiële PBI-gating` (id `cmoprewcf000qvt17pf42t0ig`) — concrete
+    spiegel-PBI van bovenstaande, in het MCP-repo.
+- Wanneer optie C overwegen: zodra er tegelijk drie of meer "spiegel-PBIs" open
+  staan op verschillende producten, of wanneer de afhankelijkheidsvolgorde
+  tussen ze leidt tot meer dan één gemiste merge per maand.
+- Re-visit: in de retro na de eerste vier cross-repo features.
--- a/docs/runbooks/agent-flow-pitfalls.md
+++ b/docs/runbooks/agent-flow-pitfalls.md
@ -0,0 +1,83 @@
+---
+title: "Agent-flow: open issues & decision log"
+status: active
+audience: [ai-agent, contributor, pb-owner]
+language: nl
+last_updated: 2026-05-03
+when_to_read: "When designing or auditing how the agent claims jobs and produces PRs across multiple stories, PBIs or products."
+---
+
+# Agent-flow: open issues & decision log
+
+Deze runbook bundelt vier valkuilen in de huidige agent-flow waarover later
+een bewuste beslissing moet vallen. Elk issue is óf gedekt door een
+bestaande PBI óf gekoppeld aan een story onder de anchor-PBI
+[`Agent-flow: openstaande beslissingen`][anchor-pbi].
+
+Status per issue is een van: `open` (nog geen besluit), `decided` (besluit
+genomen, mitigatie volgt), `mitigated` (geïmplementeerd; story gesloten).
+Promote een story naar een eigen prio-2 PBI zodra het issue acuut wordt.
+
+## 1. PBI-ordering binnen één batch — `decided`
+
+**Probleem**: in één batch kunnen jobs uit verschillende PBIs door elkaar
+lopen, omdat `wait_for_job` FIFO claimt zonder PBI-grouping.
+
+**Status**: gedekt door PBI [`Agent merge-policy: geen auto-merge,
+sequentieel per PBI`][merge-policy-pbi]. Daar wordt een gate ingebouwd
+die voorkomt dat PBI B start zolang PBI A's PR nog open is.
+
+**Niet hier dupliceren**.
+
+## 2. Schema-conflict bij parallelle Prisma-migraties — `open`
+
+**Probleem**: twee stories die elk een Prisma-migratie toevoegen krijgen
+elk een eigen migration-file met eigen timestamp. Mergen in willekeurige
+volgorde kan de schema-state inconsistent maken; oudere timestamps die
+ná nieuwere mergen geven Prisma-onverklaarbaar gedrag.
+
+**Mitigatie-opties**: sequential-gating (#1 lost dit grotendeels op),
+migration-rename CI-hook, geen agent-migrations toelaten, of
+`prisma migrate diff` als CI-gate.
+
+→ [Story `Schema-conflict tussen parallelle stories`][story-schema]
+
+## 3. Branch naam-collisie via 8-char-suffix — `open`
+
+**Probleem**: `feat/story-<last8-of-cuid>` is geen garantie tegen
+botsingen. Met genoeg stories wordt botskans niet-triviaal en de
+worktree-create faalt of vermengt commits.
+
+**Mitigatie-opties**: volledige cuid in branchnaam, `Story.code` als
+branchnaam (bv. `feat/ST-1115`), suffix-lengte verhogen, of niets doen
+en monitoren.
+
+→ [Story `Branch naam-collisie via 8-char-suffix van story-id`][story-branch]
+
+## 4. Cross-product orchestratie — `open`
+
+**Probleem**: een feature in twee producten (bv. tool in scrum4me-mcp +
+gebruik in Scrum4Me) heeft een dependency-volgorde die niet door het
+systeem wordt afgedwongen. Mergen in verkeerde volgorde breekt main.
+
+**Mitigatie-opties**: mens-discipline + description-flag,
+Initiative-laag boven PBI (ADR-0010 optie C), gating per repo-pair, of
+"blocked-by"-tekstuele link.
+
+→ [Story `Cross-product orchestratie: dependency-volgorde en
+mens-tussenstappen`][story-cross-product]
+
+## Re-visit cadans
+
+Bekijk dit document maandelijks of na elke significant agent-incident.
+Promote een story naar prio 2 zodra het issue concreet pijn doet.
+
+## Gerelateerde ADRs
+
+- [ADR-0010: Eén product = één repo; cross-product planning](../adr/0010-product-per-repo-cross-product-planning.md)
+
+[anchor-pbi]: # "PBI cmopwlxgu0016vt170ratrrur op product Scrum4Me"
+[merge-policy-pbi]: # "PBI cmoppwpwu000evt17ev2c4oo4 op product Scrum4Me"
+[story-schema]: # "Story cmopwmc0f0017vt17azn2aynr"
+[story-branch]: # "Story cmopwmqcf0018vt17583a25q2"
+[story-cross-product]: # "Story cmopwn5mc0019vt17wwrq0ib7"