Scrum4Me/docs/adr/0010-product-per-repo-cross-product-planning.md

status	date	decision-makers	consulted	informed
accepted	2026-05-03	Janpeter Visser	Claude (planning agent)	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.