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) <noreply@anthropic.com>
This commit is contained in:
parent
fdd0447aad
commit
f78b40b6b7
3 changed files with 98 additions and 1 deletions
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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) |
|
||||
|
|
|
|||
95
docs/architecture/sprint-execution-modes.md
Normal file
95
docs/architecture/sprint-execution-modes.md
Normal file
|
|
@ -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-<new_id>`.
|
||||
|
||||
---
|
||||
|
||||
## 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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue