From f78b40b6b771bb03be7831eeb7f988a495fd3d9b Mon Sep 17 00:00:00 2001 From: Madhura68 Date: Thu, 7 May 2026 12:56:15 +0200 Subject: [PATCH] PBI-50 F5: docs/architecture/sprint-execution-modes.md Vergelijking PER_TASK vs SPRINT_BATCH met trade-offs, datamodel- toevoegingen (SprintTaskExecution, lease_until, SprintRunChain) en MCP-tools-matrix per modus. Toegevoegd aan breadcrumb in docs/architecture.md. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/INDEX.md | 3 +- docs/architecture.md | 1 + docs/architecture/sprint-execution-modes.md | 95 +++++++++++++++++++++ 3 files changed, 98 insertions(+), 1 deletion(-) create mode 100644 docs/architecture/sprint-execution-modes.md diff --git a/docs/INDEX.md b/docs/INDEX.md index edf6c85..41c7ddd 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -2,7 +2,7 @@ # Documentation Index -Auto-generated on 2026-05-06 from front-matter and headings. +Auto-generated on 2026-05-07 from front-matter and headings. ## Architecture Decision Records @@ -94,6 +94,7 @@ Auto-generated on 2026-05-06 from front-matter and headings. | [Scrum4Me — Architecture Overview](./architecture/overview.md) | `architecture/overview.md` | active | 2026-05-03 | | [Project Structure, Stores, Realtime & Job Queue](./architecture/project-structure.md) | `architecture/project-structure.md` | active | 2026-05-03 | | [QR-pairing Login Flow](./architecture/qr-pairing.md) | `architecture/qr-pairing.md` | active | 2026-05-03 | +| [Sprint execution modes — PER_TASK vs SPRINT_BATCH](./architecture/sprint-execution-modes.md) | `architecture/sprint-execution-modes.md` | active | 2026-05-07 | | [Scrum4Me — Implementatie Backlog](./backlog.md) | `backlog.md` | active | 2026-05-03 | | [Scrum4Me — Implementatie Backlog](./backlog/index.md) | `backlog/index.md` | active | 2026-05-03 | | [DevPlanner — Product Backlog](./backlog/product-historical.md) | `backlog/product-historical.md` | active | 2026-05-03 | diff --git a/docs/architecture.md b/docs/architecture.md index 8ada2a6..b64e501 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -18,3 +18,4 @@ last_updated: 2026-05-03 | QR-pairing login flow | [architecture/qr-pairing.md](./architecture/qr-pairing.md) | | Claude ↔ User vraag-kanaal | [architecture/claude-question-channel.md](./architecture/claude-question-channel.md) | | Projectstructuur, Stores, Realtime, Job queue | [architecture/project-structure.md](./architecture/project-structure.md) | +| Sprint execution modes (PER_TASK vs SPRINT_BATCH) | [architecture/sprint-execution-modes.md](./architecture/sprint-execution-modes.md) | diff --git a/docs/architecture/sprint-execution-modes.md b/docs/architecture/sprint-execution-modes.md new file mode 100644 index 0000000..02ec11e --- /dev/null +++ b/docs/architecture/sprint-execution-modes.md @@ -0,0 +1,95 @@ +--- +title: "Sprint execution modes — PER_TASK vs SPRINT_BATCH" +status: active +audience: [maintainer, contributor] +language: nl +last_updated: 2026-05-07 +related: [project-structure.md](./project-structure.md), [data-model.md](./data-model.md) +--- + +# Sprint execution modes (PBI-50) + +`Product.pr_strategy` bepaalt hoe een SprintRun wordt uitgevoerd. Drie waarden: + +| Waarde | Branch + PR | Worker-sessies | Wanneer | +|---|---|---|---| +| `STORY` | branch + PR per story | één claude-sessie per task | klassieke flow; iedere story landt onafhankelijk | +| `SPRINT` | één draft-PR voor de hele sprint, mark-ready aan eind | één claude-sessie **per task** | werk wordt verzameld in één PR maar tasks blijven losse jobs | +| `SPRINT_BATCH` | één draft-PR voor de hele sprint, mark-ready aan eind | **één claude-sessie voor de hele sprint** | snelste pad; vereist alle tasks in dezelfde repo | + +`STORY` en `SPRINT` triggeren beide het PER_TASK-pad: per TO_DO-task één +`ClaudeJob` met `kind=TASK_IMPLEMENTATION`. Het verschil zit alleen in de +PR-strategie van [`maybeCreateAutoPr`](../../scrum4me-mcp/src/tools/update-job-status.ts). + +`SPRINT_BATCH` triggert het PER_SPRINT-pad: één `ClaudeJob` met +`kind=SPRINT_IMPLEMENTATION` die alle TO_DO-tasks van de sprint sequentieel +afhandelt in één claude-sessie. + +--- + +## Waarom SPRINT_BATCH + +Iedere task-claim onder PER_TASK is een verse `claude -p`-sessie. Setup-overhead +per task: laden van Claude Code + MCP-tools, project-CLAUDE.md inlezen, +codebase-oriëntatie. Bij een sprint van 12 tasks van elk 2-4 minuten effectief +werk levert dat ~10-20% pure setup-overhead op én geen continuïteit tussen +tasks. + +`SPRINT_BATCH` ruilt deze overhead in voor één lange sessie: + +``` +PER_TASK (STORY/SPRINT): SPRINT_BATCH: + task1 → setup → werk → done setup → task1 → task2 → ... → done + task2 → setup → werk → done [één heartbeat-loop, één branch, + task3 → setup → werk → done één PR, één finalisering] + ... +``` + +--- + +## Trade-offs + +| Aspect | PER_TASK | SPRINT_BATCH | +|---|---|---| +| Setup-overhead per task | hoog | éénmalig | +| Cross-repo task | toegestaan via `task.repo_url`-override | hard-fail in pre-flight (`task_cross_repo`-blocker) | +| Mid-sprint task-plan-edit | wordt direct opgepikt door volgende claim | snapshot-frozen in `SprintTaskExecution.plan_snapshot` op claim-tijd | +| Cancel/pause vanuit UI | werkt op task-niveau (volgende claim respecteert PAUSED-status) | werkt op SprintRun-niveau via `job_heartbeat`-respons (worker breekt task-loop bij `sprint_run_status !== 'RUNNING'`) | +| Failure-mode | task → cancelPbiOnFailure cascade | cascade-stop op eerste fail; sprint → FAILED, branch wordt gepusht maar PR niet ready | +| Quota-pause | niet gedefinieerd | per-task probe via `worker_heartbeat`; bij low → `QUOTA_PAUSE:`-prefix → SprintRun PAUSED met resume-instructions; resume creëert nieuwe SprintRun met `previous_run_id` + branch-hergebruik | + +--- + +## Datamodel + +`SPRINT_BATCH` introduceert: + +- `ClaudeJobKind.SPRINT_IMPLEMENTATION` — één job per SprintRun. +- `SprintTaskExecution` — frozen scope-snapshot per claim: + `{ plan_snapshot, verify_required_snapshot, verify_only_snapshot, base_sha, + head_sha, status, verify_result, verify_summary }`. Worker en gate werken + uitsluitend op deze rows; latere wijzigingen aan Task-records hebben geen + invloed op de lopende batch. +- `ClaudeJob.lease_until` — heartbeat-driven anti-stale-reset (60s interval, + 5min lease). +- `SprintRun.previous_run_id` (self-relation `SprintRunChain`) — link naar de + voorgaande run bij resume; worker hergebruikt `previous.branch` in plaats + van `feat/sprint-`. + +--- + +## MCP-tools per modus + +| Tool | PER_TASK | SPRINT_BATCH | +|---|---|---| +| `wait_for_job` | ✓ | ✓ (claim-filter discrimineert via `cj.kind`) | +| `update_task_plan` | ✓ | n/a (frozen in snapshot) | +| `verify_task_against_plan` | ✓ | n/a | +| `verify_sprint_task` | n/a | ✓ (per execution, snapshot-aware) | +| `update_task_status` | ✓ | ✓ (vereist `sprint_run_id` voor token-coupling) | +| `update_task_execution` | n/a | ✓ | +| `job_heartbeat` | ✓ (lease-extend, no sprint-fields) | ✓ (lease-extend + `sprint_run_status` poll) | +| `update_job_status` | ✓ (per-task) | ✓ (aggregate `checkSprintVerifyGate` + `finalizeSprintRunOnDone`) | + +Volledige tool-catalogus: [scrum4me-mcp README](../../scrum4me-mcp/README.md). +Worker-loop pseudocode: [scrum4me-docker CLAUDE.md](../../scrum4me-docker/CLAUDE.md).