PBI-47: schema, pause_context Zod, resumePausedSprintRunAction, PAUSED-banner UI (#137)

Scrum4Me-side counterpart of scrum4me-mcp@f7f5a48 (PBI-9 + PBI-47):

- prisma migration: ClaudeJob.{base_sha,head_sha} + SprintRun.pause_context
- lib/pause-context.ts: Zod schema + parsePauseContext + pauseReasonLabel
  helper; single source of truth for the JSON pause_context shape produced
  by the mcp sprint-run flow (MERGE_CONFLICT pause)
- actions/sprint-runs.ts: resumePausedSprintRunAction — separate from the
  existing FAILED-resume flow, requires SprintRun.status === PAUSED, closes
  the linked ClaudeQuestion, clears pause_context, sets RUNNING/QUEUED based
  on whether a claim is still active
- components/sprint/sprint-run-controls.tsx: PAUSED banner with reason label,
  PR link, conflict-files list (max 5 + "+N more"), Resume button with
  confirm() guard
- app/(app)/products/[id]/sprint/page.tsx: load pause_context from active
  SprintRun and pass through to SprintRunControls

All MD3 tokens (warning-container, on-warning-container, primary). No raw
Tailwind utility colours.

Tests: 532 passing across 72 files (Scrum4Me side).

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

actions/sprint-runs.ts

@@ -4,9 +4,10 @@ import { revalidatePath } from 'next/cache'
 import { cookies } from 'next/headers'
 import { getIronSession } from 'iron-session'
 import { z } from 'zod'
-import type { Prisma } from '@prisma/client'
+import { Prisma } from '@prisma/client'
 import { prisma } from '@/lib/prisma'
 import { SessionData, sessionOptions } from '@/lib/session'
+import { parsePauseContext } from '@/lib/pause-context'
 
 async function getSession() {
   return getIronSession<SessionData>(await cookies(), sessionOptions)
@@ -241,6 +242,68 @@ export async function resumeSprintAction(input: unknown): Promise<StartResult> {
   return result
 }
 
+const ResumePausedSprintRunInput = z.object({ sprint_run_id: z.string().min(1) })
+
+interface ResumePausedResultOk {
+  ok: true
+}
+
+type ResumePausedResult = ResumePausedResultOk | ErrorResult
+
+export async function resumePausedSprintRunAction(
+  input: unknown,
+): Promise<ResumePausedResult> {
+  const session = await getSession()
+  if (!session.userId) return { ok: false, error: 'Niet ingelogd', code: 403 }
+  if (session.isDemo)
+    return { ok: false, error: 'Niet beschikbaar in demo-modus', code: 403 }
+
+  const parsed = ResumePausedSprintRunInput.safeParse(input)
+  if (!parsed.success) return { ok: false, error: 'Validatie mislukt', code: 422 }
+
+  const sprint_run_id = parsed.data.sprint_run_id
+
+  const result = await prisma.$transaction(async (tx) => {
+    const run = await tx.sprintRun.findUnique({
+      where: { id: sprint_run_id },
+      select: { id: true, status: true, sprint_id: true, pause_context: true },
+    })
+    if (!run) return { ok: false as const, error: 'SPRINT_RUN_NOT_FOUND', code: 404 }
+    if (run.status !== 'PAUSED')
+      return { ok: false as const, error: 'SPRINT_RUN_NOT_PAUSED', code: 400 }
+
+    const ctx = parsePauseContext(run.pause_context)
+    if (ctx) {
+      await tx.claudeQuestion.updateMany({
+        where: { id: ctx.claude_question_id, status: 'open' },
+        data: { status: 'closed' },
+      })
+    }
+
+    // RUNNING when there's still a claim active, otherwise QUEUED so the
+    // worker picks up the next job on its next claim.
+    const activeClaims = await tx.claudeJob.count({
+      where: { sprint_run_id, status: { in: ['CLAIMED', 'RUNNING'] } },
+    })
+
+    await tx.sprintRun.update({
+      where: { id: sprint_run_id },
+      data: {
+        status: activeClaims > 0 ? 'RUNNING' : 'QUEUED',
+        pause_context: Prisma.JsonNull,
+      },
+    })
+
+    return { ok: true as const, sprint_id: run.sprint_id }
+  })
+
+  if (result.ok && 'sprint_id' in result) {
+    revalidatePath(`/sprints/${result.sprint_id}`)
+    return { ok: true }
+  }
+  return result
+}
+
 interface CancelResultOk {
   ok: true
 }

app/(app)/products/[id]/sprint/page.tsx

@@ -7,6 +7,7 @@ import { pbiStatusToApi } from '@/lib/task-status'
 import { SprintBoardClient } from '@/components/sprint/sprint-board-client'
 import { SprintHeader } from '@/components/sprint/sprint-header'
 import { SprintRunControls } from '@/components/sprint/sprint-run-controls'
+import { parsePauseContext } from '@/lib/pause-context'
 import type { SprintStory, PbiWithStories, ProductMember } from '@/components/sprint/sprint-backlog'
 import type { Task } from '@/components/sprint/task-list'
 import { TaskDialog } from '@/app/_components/tasks/task-dialog'
@@ -50,8 +51,13 @@ export default async function SprintBoardPage({ params, searchParams }: Props) {
       sprint_id: sprint.id,
       status: { in: ['QUEUED', 'RUNNING', 'PAUSED'] },
     },
-    select: { id: true, status: true },
+    select: { id: true, status: true, pause_context: true },
+    orderBy: { created_at: 'desc' },
   })
+  const pauseContext =
+    activeSprintRun?.status === 'PAUSED'
+      ? parsePauseContext(activeSprintRun.pause_context)
+      : null
 
   // Sprint stories with full task data and assignee
   const [sprintStories, productMembers] = await Promise.all([
@@ -163,6 +169,7 @@ export default async function SprintBoardPage({ params, searchParams }: Props) {
           sprintStatus={sprint.status}
           activeSprintRunId={activeSprintRun?.id ?? null}
           activeSprintRunStatus={activeSprintRun?.status ?? null}
+          pauseContext={pauseContext}
           isDemo={isDemo}
         />
       </div>

components/sprint/sprint-run-controls.tsx

@@ -5,6 +5,7 @@ import { toast } from 'sonner'
 import {
   startSprintRunAction,
   resumeSprintAction,
+  resumePausedSprintRunAction,
   cancelSprintRunAction,
   type PreFlightBlocker,
 } from '@/actions/sprint-runs'
@@ -17,6 +18,7 @@ import {
   DialogHeader,
   DialogTitle,
 } from '@/components/ui/dialog'
+import { type PauseContext, pauseReasonLabel } from '@/lib/pause-context'
 
 type SprintStatusValue = 'ACTIVE' | 'COMPLETED' | 'FAILED'
 type SprintRunStatusValue =
@@ -34,6 +36,7 @@ interface Props {
   sprintStatus: SprintStatusValue
   activeSprintRunId: string | null
   activeSprintRunStatus: SprintRunStatusValue
+  pauseContext: PauseContext | null
   isDemo: boolean
 }
 
@@ -60,6 +63,7 @@ export function SprintRunControls({
   sprintStatus,
   activeSprintRunId,
   activeSprintRunStatus,
+  pauseContext,
   isDemo,
 }: Props) {
   const [pending, startTransition] = useTransition()
@@ -73,6 +77,8 @@ export function SprintRunControls({
 
   const canStart = sprintStatus === 'ACTIVE' && !hasActiveRun
   const canResume = sprintStatus === 'FAILED'
+  const canResumePaused =
+    activeSprintRunStatus === 'PAUSED' && pauseContext !== null
   const canCancel = hasActiveRun
 
   function handleStart() {
@@ -101,6 +107,25 @@ export function SprintRunControls({
     })
   }
 
+  function handleResumePaused() {
+    if (!activeSprintRunId || !pauseContext) return
+    if (
+      !confirm(
+        `Sprint hervatten? Bevestig dat het ${pauseReasonLabel(
+          pauseContext.pause_reason,
+        ).toLowerCase()} is opgelost.`,
+      )
+    )
+      return
+    startTransition(async () => {
+      const result = await resumePausedSprintRunAction({
+        sprint_run_id: activeSprintRunId,
+      })
+      if (result.ok) toast.success('Sprint hervat')
+      else toast.error(result.error)
+    })
+  }
+
   function handleCancel() {
     if (!activeSprintRunId) return
     if (!confirm('Sprint annuleren? Openstaande taken blijven TO_DO.')) return
@@ -113,6 +138,39 @@ export function SprintRunControls({
 
   return (
     <>
+      {canResumePaused && pauseContext && (
+        <div className="rounded-md border border-warning/40 bg-warning-container/20 p-3 mb-2">
+          <div className="text-xs uppercase tracking-wide text-on-warning-container">
+            Gepauzeerd: {pauseReasonLabel(pauseContext.pause_reason)}
+          </div>
+          <a
+            href={pauseContext.pr_url}
+            target="_blank"
+            rel="noreferrer"
+            className="text-sm text-primary hover:underline break-all"
+          >
+            {pauseContext.pr_url}
+          </a>
+          {pauseContext.conflict_files.length > 0 && (
+            <ul className="mt-1 text-xs text-muted-foreground">
+              {pauseContext.conflict_files.slice(0, 5).map((f) => (
+                <li key={f}>· {f}</li>
+              ))}
+              {pauseContext.conflict_files.length > 5 && (
+                <li>· + {pauseContext.conflict_files.length - 5} meer</li>
+              )}
+            </ul>
+          )}
+          <Button
+            size="sm"
+            onClick={handleResumePaused}
+            disabled={pending || isDemo}
+            className="text-xs mt-2"
+          >
+            Hervat gepauzeerde sprint
+          </Button>
+        </div>
+      )}
       <div className="flex items-center gap-2">
         {canStart && (
           <Button

lib/pause-context.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod'
+
+export const PauseReasonSchema = z.enum(['MERGE_CONFLICT'])
+export type PauseReason = z.infer<typeof PauseReasonSchema>
+
+export const PauseContextSchema = z.object({
+  pause_reason: PauseReasonSchema,
+  pr_url: z.string().url(),
+  pr_head_sha: z.string().min(7),
+  conflict_files: z.array(z.string()).default([]),
+  claude_question_id: z.string().min(1),
+  resume_instructions: z.string().min(1),
+  paused_at: z.string().datetime(),
+})
+
+export type PauseContext = z.infer<typeof PauseContextSchema>
+
+export function parsePauseContext(raw: unknown): PauseContext | null {
+  if (raw === null || raw === undefined) return null
+  const parsed = PauseContextSchema.safeParse(raw)
+  return parsed.success ? parsed.data : null
+}
+
+const PAUSE_REASON_LABELS: Record<PauseReason, string> = {
+  MERGE_CONFLICT: 'Merge-conflict op PR',
+}
+
+export function pauseReasonLabel(reason: PauseReason): string {
+  return PAUSE_REASON_LABELS[reason] ?? reason
+}

prisma/migrations/20260506182000_add_job_shas_and_pause_context/migration.sql

@@ -0,0 +1,10 @@
+-- Add base_sha + head_sha to ClaudeJob (per-job verify scope + merge-guard).
+-- Add pause_context to SprintRun (rich PAUSED-state for merge-conflicts).
+-- All nullable so legacy rows remain valid; new code-paths set them.
+
+-- AlterTable
+ALTER TABLE "claude_jobs" ADD COLUMN     "base_sha" TEXT,
+ADD COLUMN     "head_sha" TEXT;
+
+-- AlterTable
+ALTER TABLE "sprint_runs" ADD COLUMN     "pause_context" JSONB;

prisma/schema.prisma

@@ -318,6 +318,7 @@ model SprintRun {
   failure_reason String?
   failed_task    Task?           @relation("SprintRunFailedTask", fields: [failed_task_id], references: [id], onDelete: SetNull)
   failed_task_id String?
+  pause_context  Json?
   created_at     DateTime        @default(now())
   updated_at     DateTime        @updatedAt
   jobs           ClaudeJob[]
@@ -389,6 +390,8 @@ model ClaudeJob {
   cache_read_tokens   Int?
   cache_write_tokens  Int?
   plan_snapshot       String?
+  base_sha            String?
+  head_sha            String?
   branch              String?
   pr_url              String?
   summary             String?