janpeter/Scrum4Me
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

PBI-50: SPRINT_IMPLEMENTATION single-session sprint runner (Scrum4Me-side) (#139)

Browse source 
* PBI-50 F1: SPRINT_BATCH execution-strategy + cross-repo blocker + branch-resume

Schema-migratie + Scrum4Me-side wiring voor de nieuwe SPRINT_IMPLEMENTATION-flow:

- prisma: PrStrategy ADD VALUE 'SPRINT_BATCH'; ClaudeJobKind ADD VALUE
  'SPRINT_IMPLEMENTATION'; nieuwe enum SprintTaskExecutionStatus; ClaudeJob.lease_until
  + status_lease_until index; SprintRun.previous_run_id (self-relation
  SprintRunChain) voor branch-hergebruik bij resume; nieuwe sprint_task_executions
  tabel met frozen plan_snapshot + verify_required_snapshot per task in scope.
- actions/sprint-runs.ts startSprintRunCore: nieuwe blocker-type 'task_cross_repo'
  voor SPRINT_BATCH (pre-flight rejecteert sprints met cross-repo task_url).
  Bij SPRINT_BATCH: één SPRINT_IMPLEMENTATION ClaudeJob (geen per-task loop).
- actions/sprint-runs.ts resumePausedSprintRunAction: SPRINT_BATCH-pad met
  remaining-execution-check; bij onafgemaakt werk → nieuwe SprintRun met
  previous_run_id + run.branch hergebruikt + nieuwe SPRINT_IMPLEMENTATION-job.
  Oude SprintRun → CANCELLED. Bestaande PBI-49 P0 scope-DONE pad ongewijzigd.
- actions/products.ts updatePrStrategyAction: accepteert SPRINT_BATCH.
- components/products/pr-strategy-select.tsx: drie opties met helptekst,
  gebruikt @prisma/client PrStrategy ipv lokaal type.
- components/sprint/sprint-run-controls.tsx: BLOCKER_LABELS + blockerHref
  voor task_cross_repo.

Migratie applied op Neon. Type-check + 532 tests groen.

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

* PBI-50 F5: cross-repo blocker test voor SPRINT_BATCH

- task_cross_repo blocker fires bij task.repo_url ≠ product.repo_url
- happy path: tasks zonder repo_url-override of met match → één
  SPRINT_IMPLEMENTATION-job (niet per-task).

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

* 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>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Janpeter Visser 2026-05-07 13:05:02 +02:00 • committed by GitHub
parent e6dcc91383
commit 07749ad9fb
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 490 additions and 69 deletions
Download patch file Download diff file Expand all files Collapse all files

100
__tests__/actions/sprint-runs.test.ts
View file

@ -201,6 +201,106 @@ describe('startSprintRunAction — pre-flight blockers', () => {
}) })
}) })
describe('startSprintRunAction — SPRINT_BATCH', () => {
const SPRINT_BATCH = {
...SPRINT_OK,
product: {
id: 'prod-1',
pr_strategy: 'SPRINT_BATCH',
repo_url: 'https://github.com/example/main',
},
}
it('blokkeert task met afwijkende repo_url', async () => {
mockPrisma.sprint.findUnique.mockResolvedValue(SPRINT_BATCH)
mockPrisma.sprintRun.findFirst.mockResolvedValue(null)
mockPrisma.story.findMany.mockResolvedValue([
{
...STORY_OK,
tasks: [
{
id: 'task-1',
code: 'T-1',
title: 'In main repo',
priority: 1,
sort_order: 1,
implementation_plan: 'plan',
repo_url: null,
},
{
id: 'task-2',
code: 'T-2',
title: 'Cross-repo',
priority: 1,
sort_order: 2,
implementation_plan: 'plan',
repo_url: 'https://github.com/example/other',
},
],
},
])
mockPrisma.claudeQuestion.findMany.mockResolvedValue([])
const result = await startSprintRunAction({ sprint_id: 'sprint-1' })
expect(result).toMatchObject({ ok: false, error: 'PRE_FLIGHT_BLOCKED' })
if (result.ok === false && 'blockers' in result) {
expect(result.blockers).toContainEqual({
type: 'task_cross_repo',
id: 'task-2',
label: 'T-2: Cross-repo',
})
}
expect(mockPrisma.sprintRun.create).not.toHaveBeenCalled()
})
it('staat tasks toe wanneer repo_url leeg is of gelijk aan product.repo_url', async () => {
mockPrisma.sprint.findUnique.mockResolvedValue(SPRINT_BATCH)
mockPrisma.sprintRun.findFirst.mockResolvedValue(null)
mockPrisma.story.findMany.mockResolvedValue([
{
...STORY_OK,
tasks: [
{
id: 'task-1',
code: 'T-1',
title: 'No override',
priority: 1,
sort_order: 1,
implementation_plan: 'plan',
repo_url: null,
},
{
id: 'task-2',
code: 'T-2',
title: 'Same repo',
priority: 1,
sort_order: 2,
implementation_plan: 'plan',
repo_url: 'https://github.com/example/main',
},
],
},
])
mockPrisma.claudeQuestion.findMany.mockResolvedValue([])
mockPrisma.sprintRun.create.mockResolvedValue({ id: 'run-batch' })
mockPrisma.claudeJob.create.mockResolvedValue({ id: 'job-sprint' })
const result = await startSprintRunAction({ sprint_id: 'sprint-1' })
expect(result).toMatchObject({ ok: true, sprint_run_id: 'run-batch' })
// Eén SPRINT_IMPLEMENTATION-job, niet per-task
expect(mockPrisma.claudeJob.create).toHaveBeenCalledTimes(1)
expect(mockPrisma.claudeJob.create).toHaveBeenCalledWith({
data: expect.objectContaining({
kind: 'SPRINT_IMPLEMENTATION',
sprint_run_id: 'run-batch',
product_id: 'prod-1',
}),
})
})
})
describe('startSprintRunAction — guards', () => { describe('startSprintRunAction — guards', () => {
it('weigert wanneer Sprint niet ACTIVE is', async () => { it('weigert wanneer Sprint niet ACTIVE is', async () => {
mockPrisma.sprint.findUnique.mockResolvedValue({ ...SPRINT_OK, status: 'COMPLETED' }) mockPrisma.sprint.findUnique.mockResolvedValue({ ...SPRINT_OK, status: 'COMPLETED' })

4
actions/products.ts
View file

@ -399,14 +399,14 @@ export async function updateAutoPrAction(id: string, auto_pr: boolean) {
export async function updatePrStrategyAction( export async function updatePrStrategyAction(
id: string, id: string,
pr_strategy: 'SPRINT' | 'STORY', pr_strategy: 'SPRINT' | 'STORY' | 'SPRINT_BATCH',
) { ) {
const session = await getSession() const session = await getSession()
if (!session.userId) return { error: 'Niet ingelogd' } if (!session.userId) return { error: 'Niet ingelogd' }
if (session.isDemo) return { error: 'Niet beschikbaar in demo-modus' } if (session.isDemo) return { error: 'Niet beschikbaar in demo-modus' }
const parsed = z const parsed = z
.object({ pr_strategy: z.enum(['SPRINT', 'STORY']) }) .object({ pr_strategy: z.enum(['SPRINT', 'STORY', 'SPRINT_BATCH']) })
.safeParse({ pr_strategy }) .safeParse({ pr_strategy })
if (!parsed.success) return { error: 'Ongeldige waarde voor pr_strategy' } if (!parsed.success) return { error: 'Ongeldige waarde voor pr_strategy' }

113
actions/sprint-runs.ts
View file

@ -13,7 +13,11 @@ async function getSession() {
return getIronSession<SessionData>(await cookies(), sessionOptions) return getIronSession<SessionData>(await cookies(), sessionOptions)
} }
export type PreFlightBlockerType = 'task_no_plan' | 'open_question' | 'pbi_blocked' export type PreFlightBlockerType =
| 'task_no_plan'
| 'open_question'
| 'pbi_blocked'
| 'task_cross_repo'
export interface PreFlightBlocker { export interface PreFlightBlocker {
type: PreFlightBlockerType type: PreFlightBlockerType
@ -122,6 +126,23 @@ async function startSprintRunCore(
} }
} }
// PBI-50: SPRINT_BATCH cross-repo blocker. Eén product-worktree =
// alle tasks moeten in product.repo_url werken; task.repo_url-override
// is incompatibel met deze flow.
if (sprint.product.pr_strategy === 'SPRINT_BATCH') {
for (const s of stories) {
for (const t of s.tasks) {
if (t.repo_url && t.repo_url !== sprint.product.repo_url) {
blockers.push({
type: 'task_cross_repo',
id: t.id,
label: `${t.code}: ${t.title}`,
})
}
}
}
}
if (blockers.length > 0) { if (blockers.length > 0) {
return { ok: false, error: 'PRE_FLIGHT_BLOCKED', blockers } return { ok: false, error: 'PRE_FLIGHT_BLOCKED', blockers }
} }
@ -147,6 +168,26 @@ async function startSprintRunCore(
) )
.flatMap((s) => s.tasks) .flatMap((s) => s.tasks)
// PBI-50: SPRINT_BATCH levert één SPRINT_IMPLEMENTATION-job die alle
// tasks in één claude-sessie afhandelt. SprintTaskExecution-rows worden
// server-side bij claim aangemaakt zodat order/base_sha consistent zijn
// met de worktree-state op claim-tijd.
if (sprint.product.pr_strategy === 'SPRINT_BATCH') {
await tx.claudeJob.create({
data: {
user_id,
product_id: sprint.product_id,
task_id: null,
idea_id: null,
sprint_run_id: sprintRun.id,
kind: 'SPRINT_IMPLEMENTATION',
status: 'QUEUED',
},
})
return { ok: true, sprint_run_id: sprintRun.id, jobs_count: 1 }
}
// STORY / SPRINT (per-task): bestaand pad.
for (const t of orderedTasks) { for (const t of orderedTasks) {
await tx.claudeJob.create({ await tx.claudeJob.create({
data: { data: {
@ -263,10 +304,18 @@ export async function resumePausedSprintRunAction(
const sprint_run_id = parsed.data.sprint_run_id const sprint_run_id = parsed.data.sprint_run_id
const userId = session.userId
const result = await prisma.$transaction(async (tx) => { const result = await prisma.$transaction(async (tx) => {
const run = await tx.sprintRun.findUnique({ const run = await tx.sprintRun.findUnique({
where: { id: sprint_run_id }, where: { id: sprint_run_id },
select: { id: true, status: true, sprint_id: true, pause_context: true }, select: {
id: true,
status: true,
sprint_id: true,
pr_strategy: true,
branch: true,
pause_context: true,
},
}) })
if (!run) return { ok: false as const, error: 'SPRINT_RUN_NOT_FOUND', code: 404 } if (!run) return { ok: false as const, error: 'SPRINT_RUN_NOT_FOUND', code: 404 }
if (run.status !== 'PAUSED') if (run.status !== 'PAUSED')
@ -280,6 +329,57 @@ export async function resumePausedSprintRunAction(
}) })
} }
// PBI-50: SPRINT_BATCH resume-pad — als de SprintRun hangt aan een
// SPRINT_IMPLEMENTATION-job en er nog onafgemaakte SprintTaskExecution-rows
// zijn (PENDING/RUNNING), maak NIEUWE SprintRun met previous_run_id +
// hergebruikte branch + nieuwe SPRINT_IMPLEMENTATION-job. Oude SprintRun
// gaat naar CANCELLED.
const sprintJob = await tx.claudeJob.findFirst({
where: { sprint_run_id, kind: 'SPRINT_IMPLEMENTATION' },
select: { id: true, product_id: true },
})
if (sprintJob) {
const remaining = await tx.sprintTaskExecution.count({
where: {
sprint_job_id: sprintJob.id,
status: { in: ['PENDING', 'RUNNING'] },
},
})
if (remaining > 0) {
const newRun = await tx.sprintRun.create({
data: {
sprint_id: run.sprint_id,
started_by_id: userId,
status: 'QUEUED',
pr_strategy: run.pr_strategy,
branch: run.branch,
previous_run_id: run.id,
started_at: new Date(),
},
})
await tx.claudeJob.create({
data: {
user_id: userId,
product_id: sprintJob.product_id,
task_id: null,
idea_id: null,
sprint_run_id: newRun.id,
kind: 'SPRINT_IMPLEMENTATION',
status: 'QUEUED',
},
})
await tx.sprintRun.update({
where: { id: sprint_run_id },
data: {
status: 'CANCELLED',
pause_context: Prisma.JsonNull,
finished_at: new Date(),
},
})
return { ok: true as const, sprint_id: run.sprint_id, finalStatus: 'QUEUED' as const }
}
}
const activeClaims = await tx.claudeJob.count({ const activeClaims = await tx.claudeJob.count({
where: { sprint_run_id, status: { in: ['CLAIMED', 'RUNNING'] } }, where: { sprint_run_id, status: { in: ['CLAIMED', 'RUNNING'] } },
}) })
@ -287,11 +387,10 @@ export async function resumePausedSprintRunAction(
where: { sprint_run_id, status: 'QUEUED' }, where: { sprint_run_id, status: 'QUEUED' },
}) })
// PBI-49 P0: a STORY auto-merge MERGE_CONFLICT lands AFTER all tasks are // PBI-49 P0: een STORY auto-merge MERGE_CONFLICT komt NA dat alle tasks
// already DONE (storyBecameDone fires the conflict). Going back to QUEUED // al DONE zijn. Terug naar QUEUED zou de SprintRun voor altijd laten
// would hang the SprintRun forever — there is no QUEUED job to claim. // hangen — geen QUEUED job. Bij volledige scope-completion transitie
// When the scope is fully complete, transition straight to DONE; the // direct naar DONE; de dev heeft het conflict opgelost, de PR is van hen.
// dev resolved the conflict manually and the PR is theirs to merge.
let nextStatus: 'RUNNING' | 'QUEUED' | 'DONE' let nextStatus: 'RUNNING' | 'QUEUED' | 'DONE'
let finishedAt: Date | undefined let finishedAt: Date | undefined
if (activeClaims === 0 && queuedJobs === 0) { if (activeClaims === 0 && queuedJobs === 0) {

20
components/products/pr-strategy-select.tsx
View file

@ -2,6 +2,7 @@
import { useState, useTransition } from 'react' import { useState, useTransition } from 'react'
import { toast } from 'sonner' import { toast } from 'sonner'
import type { PrStrategy } from '@prisma/client'
import { updatePrStrategyAction } from '@/actions/products' import { updatePrStrategyAction } from '@/actions/products'
import { import {
Select, Select,
@ -10,29 +11,33 @@ import {
SelectTrigger, SelectTrigger,
} from '@/components/ui/select' } from '@/components/ui/select'
type PrStrategy = 'SPRINT' | 'STORY'
interface PrStrategySelectProps { interface PrStrategySelectProps {
productId: string productId: string
initialValue: PrStrategy initialValue: PrStrategy
} }
const STRATEGY_LABELS: Record<PrStrategy, string> = { const STRATEGY_LABELS: Record<PrStrategy, string> = {
SPRINT: 'Per sprint — één PR voor de hele sprint, klaar voor review aan eind', SPRINT:
STORY: 'Per story — auto-merge na CI groen, één PR per story', 'Per sprint — één PR voor de hele sprint, klaar voor review aan eind. Per task een eigen claude-sessie.',
STORY:
'Per story — auto-merge na CI groen, één PR per story. Per task een eigen claude-sessie.',
SPRINT_BATCH:
'Sprint batch — één claude-sessie voor de hele sprint, sneller en behoudt context. Vereist alle tasks in de product-hoofdrepo.',
} }
const VALID_VALUES: ReadonlyArray<PrStrategy> = ['SPRINT', 'STORY', 'SPRINT_BATCH']
export function PrStrategySelect({ productId, initialValue }: PrStrategySelectProps) { export function PrStrategySelect({ productId, initialValue }: PrStrategySelectProps) {
const [value, setValue] = useState<PrStrategy>(initialValue) const [value, setValue] = useState<PrStrategy>(initialValue)
const [isPending, startTransition] = useTransition() const [isPending, startTransition] = useTransition()
function handleChange(next: string | null) { function handleChange(next: string | null) {
if (next !== 'SPRINT' && next !== 'STORY') return if (!next || !VALID_VALUES.includes(next as PrStrategy)) return
if (next === value) return if (next === value) return
const previous = value const previous = value
setValue(next) setValue(next as PrStrategy)
startTransition(async () => { startTransition(async () => {
const result = await updatePrStrategyAction(productId, next) const result = await updatePrStrategyAction(productId, next as PrStrategy)
if ('error' in result && result.error) { if ('error' in result && result.error) {
setValue(previous) setValue(previous)
toast.error(typeof result.error === 'string' ? result.error : 'Opslaan mislukt') toast.error(typeof result.error === 'string' ? result.error : 'Opslaan mislukt')
@ -49,6 +54,7 @@ export function PrStrategySelect({ productId, initialValue }: PrStrategySelectPr
<SelectContent> <SelectContent>
<SelectItem value="SPRINT">{STRATEGY_LABELS.SPRINT}</SelectItem> <SelectItem value="SPRINT">{STRATEGY_LABELS.SPRINT}</SelectItem>
<SelectItem value="STORY">{STRATEGY_LABELS.STORY}</SelectItem> <SelectItem value="STORY">{STRATEGY_LABELS.STORY}</SelectItem>
<SelectItem value="SPRINT_BATCH">{STRATEGY_LABELS.SPRINT_BATCH}</SelectItem>
</SelectContent> </SelectContent>
</Select> </Select>
</div> </div>

3
components/sprint/sprint-run-controls.tsx
View file

@ -44,6 +44,7 @@ const BLOCKER_LABELS: Record<PreFlightBlocker['type'], string> = {
task_no_plan: 'Task zonder implementation plan', task_no_plan: 'Task zonder implementation plan',
open_question: 'Openstaande vraag aan jou', open_question: 'Openstaande vraag aan jou',
pbi_blocked: 'PBI is geblokkeerd of gefaald', pbi_blocked: 'PBI is geblokkeerd of gefaald',
task_cross_repo: 'Task met afwijkende repo (niet toegestaan in SPRINT_BATCH)',
} }
function blockerHref(productId: string, blocker: PreFlightBlocker): string { function blockerHref(productId: string, blocker: PreFlightBlocker): string {
@ -54,6 +55,8 @@ function blockerHref(productId: string, blocker: PreFlightBlocker): string {
return `/products/${productId}/sprint` return `/products/${productId}/sprint`
case 'pbi_blocked': case 'pbi_blocked':
return `/products/${productId}` return `/products/${productId}`
case 'task_cross_repo':
return `/products/${productId}/sprint?editTask=${blocker.id}`
} }
} }

3
docs/INDEX.md
View file

@ -2,7 +2,7 @@
# Documentation Index # 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 ## 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 | | [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 | | [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 | | [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.md) | `backlog.md` | active | 2026-05-03 |
| [Scrum4Me — Implementatie Backlog](./backlog/index.md) | `backlog/index.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 | | [DevPlanner — Product Backlog](./backlog/product-historical.md) | `backlog/product-historical.md` | active | 2026-05-03 |

1
docs/architecture.md
View file

@ -18,3 +18,4 @@ last_updated: 2026-05-03
| QR-pairing login flow | [architecture/qr-pairing.md](./architecture/qr-pairing.md) | | 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) | | 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) | | 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
View 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).

68
prisma/migrations/20260507103000_sprint_implementation/migration.sql Normal file
View file

@ -0,0 +1,68 @@
-- PBI-50: SPRINT_IMPLEMENTATION single-session sprint runner
-- Adds:
-- - PrStrategy.SPRINT_BATCH (third option)
-- - ClaudeJobKind.SPRINT_IMPLEMENTATION (fifth kind)
-- - SprintTaskExecutionStatus enum
-- - ClaudeJob.lease_until (for heartbeat-driven stale detection)
-- - SprintRun.previous_run_id (for branch reuse on resume)
-- - sprint_task_executions table (frozen scope-snapshot per claim)
-- AlterEnum: PrStrategy ADD VALUE (Postgres requires this outside transaction;
-- Prisma migrate handles it)
ALTER TYPE "PrStrategy" ADD VALUE 'SPRINT_BATCH';
-- AlterEnum: ClaudeJobKind ADD VALUE
ALTER TYPE "ClaudeJobKind" ADD VALUE 'SPRINT_IMPLEMENTATION';
-- CreateEnum
CREATE TYPE "SprintTaskExecutionStatus" AS ENUM ('PENDING', 'RUNNING', 'DONE', 'FAILED', 'SKIPPED');
-- AlterTable
ALTER TABLE "claude_jobs" ADD COLUMN "lease_until" TIMESTAMP(3);
-- AlterTable
ALTER TABLE "sprint_runs" ADD COLUMN "previous_run_id" TEXT;
-- CreateTable
CREATE TABLE "sprint_task_executions" (
"id" TEXT NOT NULL,
"sprint_job_id" TEXT NOT NULL,
"task_id" TEXT NOT NULL,
"order" INTEGER NOT NULL,
"plan_snapshot" TEXT NOT NULL,
"verify_required_snapshot" "VerifyRequired" NOT NULL,
"verify_only_snapshot" BOOLEAN NOT NULL DEFAULT false,
"base_sha" TEXT,
"head_sha" TEXT,
"status" "SprintTaskExecutionStatus" NOT NULL DEFAULT 'PENDING',
"verify_result" "VerifyResult",
"verify_summary" TEXT,
"skip_reason" TEXT,
"started_at" TIMESTAMP(3),
"finished_at" TIMESTAMP(3),
"created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
"updated_at" TIMESTAMP(3) NOT NULL,
CONSTRAINT "sprint_task_executions_pkey" PRIMARY KEY ("id")
);
-- CreateIndex
CREATE INDEX "sprint_task_executions_sprint_job_id_order_idx" ON "sprint_task_executions"("sprint_job_id", "order");
-- CreateIndex
CREATE UNIQUE INDEX "sprint_task_executions_sprint_job_id_task_id_key" ON "sprint_task_executions"("sprint_job_id", "task_id");
-- CreateIndex
CREATE INDEX "claude_jobs_status_lease_until_idx" ON "claude_jobs"("status", "lease_until");
-- CreateIndex
CREATE UNIQUE INDEX "sprint_runs_previous_run_id_key" ON "sprint_runs"("previous_run_id");
-- AddForeignKey
ALTER TABLE "sprint_runs" ADD CONSTRAINT "sprint_runs_previous_run_id_fkey" FOREIGN KEY ("previous_run_id") REFERENCES "sprint_runs"("id") ON DELETE SET NULL ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "sprint_task_executions" ADD CONSTRAINT "sprint_task_executions_sprint_job_id_fkey" FOREIGN KEY ("sprint_job_id") REFERENCES "claude_jobs"("id") ON DELETE CASCADE ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "sprint_task_executions" ADD CONSTRAINT "sprint_task_executions_task_id_fkey" FOREIGN KEY ("task_id") REFERENCES "tasks"("id") ON DELETE CASCADE ON UPDATE CASCADE;

152
prisma/schema.prisma
View file

@ -92,6 +92,7 @@ enum SprintRunStatus {
enum PrStrategy { enum PrStrategy {
SPRINT SPRINT
STORY STORY
SPRINT_BATCH
} }
enum IdeaStatus { enum IdeaStatus {
@ -110,6 +111,15 @@ enum ClaudeJobKind {
IDEA_GRILL IDEA_GRILL
IDEA_MAKE_PLAN IDEA_MAKE_PLAN
PLAN_CHAT PLAN_CHAT
SPRINT_IMPLEMENTATION
}
enum SprintTaskExecutionStatus {
PENDING
RUNNING
DONE
FAILED
SKIPPED
} }
enum IdeaLogType { enum IdeaLogType {
@ -304,24 +314,27 @@ model Sprint {
} }
model SprintRun { model SprintRun {
id String @id @default(cuid()) id String @id @default(cuid())
sprint Sprint @relation(fields: [sprint_id], references: [id], onDelete: Cascade) sprint Sprint @relation(fields: [sprint_id], references: [id], onDelete: Cascade)
sprint_id String sprint_id String
started_by User @relation("SprintRunStartedBy", fields: [started_by_id], references: [id]) started_by User @relation("SprintRunStartedBy", fields: [started_by_id], references: [id])
started_by_id String started_by_id String
status SprintRunStatus @default(QUEUED) status SprintRunStatus @default(QUEUED)
pr_strategy PrStrategy pr_strategy PrStrategy
branch String? branch String?
pr_url String? pr_url String?
started_at DateTime? started_at DateTime?
finished_at DateTime? finished_at DateTime?
failure_reason String? failure_reason String?
failed_task Task? @relation("SprintRunFailedTask", fields: [failed_task_id], references: [id], onDelete: SetNull) failed_task Task? @relation("SprintRunFailedTask", fields: [failed_task_id], references: [id], onDelete: SetNull)
failed_task_id String? failed_task_id String?
pause_context Json? pause_context Json?
created_at DateTime @default(now()) previous_run_id String? @unique
updated_at DateTime @updatedAt previous_run SprintRun? @relation("SprintRunChain", fields: [previous_run_id], references: [id], onDelete: SetNull)
jobs ClaudeJob[] next_run SprintRun? @relation("SprintRunChain")
created_at DateTime @default(now())
updated_at DateTime @updatedAt
jobs ClaudeJob[]
@@index([sprint_id, status]) @@index([sprint_id, status])
@@index([started_by_id, status]) @@index([started_by_id, status])
@ -329,32 +342,33 @@ model SprintRun {
} }
model Task { model Task {
id String @id @default(cuid()) id String @id @default(cuid())
story Story @relation(fields: [story_id], references: [id], onDelete: Cascade) story Story @relation(fields: [story_id], references: [id], onDelete: Cascade)
story_id String story_id String
product Product @relation(fields: [product_id], references: [id], onDelete: Cascade) product Product @relation(fields: [product_id], references: [id], onDelete: Cascade)
product_id String product_id String
sprint Sprint? @relation(fields: [sprint_id], references: [id]) sprint Sprint? @relation(fields: [sprint_id], references: [id])
sprint_id String? sprint_id String?
code String @db.VarChar(30) code String @db.VarChar(30)
title String title String
description String? description String?
implementation_plan String? implementation_plan String?
priority Int priority Int
sort_order Float sort_order Float
status TaskStatus @default(TO_DO) status TaskStatus @default(TO_DO)
verify_only Boolean @default(false) verify_only Boolean @default(false)
verify_required VerifyRequired @default(ALIGNED_OR_PARTIAL) verify_required VerifyRequired @default(ALIGNED_OR_PARTIAL)
// Override product.repo_url for branch/worktree/push purposes. Set when // Override product.repo_url for branch/worktree/push purposes. Set when
// a task targets a different repo than its parent product (e.g. an // a task targets a different repo than its parent product (e.g. an
// MCP-server task tracked under the main product's PBI). Falls back to // MCP-server task tracked under the main product's PBI). Falls back to
// product.repo_url when null. // product.repo_url when null.
repo_url String? repo_url String?
created_at DateTime @default(now()) created_at DateTime @default(now())
updated_at DateTime @updatedAt updated_at DateTime @updatedAt
claude_questions ClaudeQuestion[] claude_questions ClaudeQuestion[]
claude_jobs ClaudeJob[] claude_jobs ClaudeJob[]
sprint_run_failures SprintRun[] @relation("SprintRunFailedTask") sprint_run_failures SprintRun[] @relation("SprintRunFailedTask")
sprint_task_executions SprintTaskExecution[]
@@unique([product_id, code]) @@unique([product_id, code])
@@index([story_id, priority, sort_order]) @@index([story_id, priority, sort_order])
@ -364,20 +378,20 @@ model Task {
} }
model ClaudeJob { model ClaudeJob {
id String @id @default(cuid()) id String @id @default(cuid())
user User @relation(fields: [user_id], references: [id], onDelete: Cascade) user User @relation(fields: [user_id], references: [id], onDelete: Cascade)
user_id String user_id String
product Product @relation(fields: [product_id], references: [id], onDelete: Cascade) product Product @relation(fields: [product_id], references: [id], onDelete: Cascade)
product_id String product_id String
task Task? @relation(fields: [task_id], references: [id], onDelete: Cascade) task Task? @relation(fields: [task_id], references: [id], onDelete: Cascade)
task_id String? task_id String?
idea Idea? @relation(fields: [idea_id], references: [id], onDelete: Cascade) idea Idea? @relation(fields: [idea_id], references: [id], onDelete: Cascade)
idea_id String? idea_id String?
sprint_run SprintRun? @relation(fields: [sprint_run_id], references: [id], onDelete: SetNull) sprint_run SprintRun? @relation(fields: [sprint_run_id], references: [id], onDelete: SetNull)
sprint_run_id String? sprint_run_id String?
kind ClaudeJobKind @default(TASK_IMPLEMENTATION) kind ClaudeJobKind @default(TASK_IMPLEMENTATION)
status ClaudeJobStatus @default(QUEUED) status ClaudeJobStatus @default(QUEUED)
claimed_by_token ApiToken? @relation(fields: [claimed_by_token_id], references: [id], onDelete: SetNull) claimed_by_token ApiToken? @relation(fields: [claimed_by_token_id], references: [id], onDelete: SetNull)
claimed_by_token_id String? claimed_by_token_id String?
claimed_at DateTime? claimed_at DateTime?
started_at DateTime? started_at DateTime?
@ -396,9 +410,11 @@ model ClaudeJob {
pr_url String? pr_url String?
summary String? summary String?
error String? error String?
retry_count Int @default(0) retry_count Int @default(0)
created_at DateTime @default(now()) lease_until DateTime?
updated_at DateTime @updatedAt task_executions SprintTaskExecution[] @relation("SprintJobExecutions")
created_at DateTime @default(now())
updated_at DateTime @updatedAt
@@index([user_id, status]) @@index([user_id, status])
@@index([task_id, status]) @@index([task_id, status])
@ -406,9 +422,41 @@ model ClaudeJob {
@@index([sprint_run_id, status]) @@index([sprint_run_id, status])
@@index([status, claimed_at]) @@index([status, claimed_at])
@@index([status, finished_at]) @@index([status, finished_at])
@@index([status, lease_until])
@@map("claude_jobs") @@map("claude_jobs")
} }
// PBI-50: frozen scope-snapshot per SPRINT_IMPLEMENTATION-claim. Bij claim
// wordt voor elke TO_DO-task in scope één PENDING-record gemaakt met
// implementation_plan + verify_required gesnapshot. Worker en gate werken
// uitsluitend op deze rows; latere wijzigingen aan Task hebben geen
// invloed op de lopende batch.
model SprintTaskExecution {
id String @id @default(cuid())
sprint_job ClaudeJob @relation("SprintJobExecutions", fields: [sprint_job_id], references: [id], onDelete: Cascade)
sprint_job_id String
task Task @relation(fields: [task_id], references: [id], onDelete: Cascade)
task_id String
order Int
plan_snapshot String @db.Text
verify_required_snapshot VerifyRequired
verify_only_snapshot Boolean @default(false)
base_sha String?
head_sha String?
status SprintTaskExecutionStatus @default(PENDING)
verify_result VerifyResult?
verify_summary String? @db.Text
skip_reason String? @db.Text
started_at DateTime?
finished_at DateTime?
created_at DateTime @default(now())
updated_at DateTime @updatedAt
@@unique([sprint_job_id, task_id])
@@index([sprint_job_id, order])
@@map("sprint_task_executions")
}
model ModelPrice { model ModelPrice {
id String @id @default(cuid()) id String @id @default(cuid())
model_id String @unique model_id String @unique