Scrum4Me/docs/plans/M11-claude-questions.md
Janpeter Visser 9587ff4ff3
M11: Claude vraagt, gebruiker antwoordt (ST-1101..ST-1108) (#13)
* docs(ST-1101..1108): add M11 — Claude question-channel milestone to backlog

Plant acht stories ST-1101..ST-1108 voor het persistente vraag-antwoord-kanaal
tussen Claude (MCP) en de actieve gebruiker. Eerste concrete uitwerking van
de AI-driven dev-flow-richting (strategisch besluit "B" uit overleg na M10).

Beveiligingsuitgangspunt: atomic answer via updateMany WHERE status='open',
demo-blok op write-tools, access-check via productAccessFilter in DB-query én
SSE-filter, cron-endpoint via Bearer-secret, geen vraag/antwoord-tekst in logs.

Hergebruikt bestaande scrum4me_changes-channel (uitgebreid met entity:'question')
en het LISTEN/NOTIFY+ReadableStream-pattern uit M8/M10. Nieuw: user-scoped SSE
op /api/realtime/notifications zodat de bell globaal werkt over producten heen.

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

* chore(M11): swap demo-active sprint from M10 to M11

M10 is gemerged en afgesloten — M11 wordt de nieuwe demo-actieve milestone
zodat get_claude_context (via MCP) ST-1101 als next-story teruggeeft.

Drie maps in parse-backlog.ts uitgebreid: M11 priority=4, goal omschrijving,
sprint_status='ACTIVE'. M10 → COMPLETED.

Vereist npx prisma db seed na deze commit zodat de live DB de nieuwe
sprint-state weerspiegelt.

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

* docs(ST-1108): add F-11b — Claude question-channel to functional spec

Voegt feature-omschrijving toe naast bestaande F-11 (Claude Code REST API).
Beschrijft het verloop (Claude → MCP-tool → DB → trigger → SSE → user → answer
→ trigger → Claude polls), acceptatiecriteria (8 items), randgevallen (offline-
Claude, assignee-change, expiry, abuse) en datamodel (claude_questions tabel).

Persona Lars als primair, Dina secundair voor klant-werk.

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

* chore(M11): drop parser ACTIVE-flip; sprint goes via UI from now on

Bij M9/M10 hebben we de seed-flip (MILESTONE_SPRINT_STATUS pivot) gebruikt om
nieuwe stories als IN_SPRINT in een verse sprint te krijgen. Dat werkt maar
is fragiel:
- npm run seed wist user-data
- de "sprint" die de seed maakt is geen echte planning-actie
- bij multi-product scenario's breekt het model

Vanaf M11 gebruiken we de bestaande Sprint-creatie-UI van Scrum4Me. Stories
voor M11 worden via scripts/insert-milestone.ts (idempotent insert, geen
seed-reset) aan de DB toegevoegd; de gebruiker maakt zelf een Sprint aan in
/products/[scrum4me]/sprint en sleept ST-1101..1108 ernaartoe.

Parser-map M11 dus terug naar COMPLETED zodat een eventuele re-seed niet meer
een fake sprint aanmaakt voor M11-stories.

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

* feat(ST-1101): add ClaudeQuestion model + notify_question_change trigger

Schema (prisma/schema.prisma):
- Nieuw model ClaudeQuestion: id (cuid), story_id (FK Cascade), task_id?
  (FK SetNull), product_id (FK Cascade — gedenormaliseerd uit story.product_id
  voor SSE-filter zonder join), asked_by (FK Restrict — Claude-token-houder),
  question (Text), options (Json? — string[] voor multi-choice), status
  ('open'|'answered'|'cancelled'|'expired'), answer (Text?), answered_by
  (FK SetNull), answered_at?, created_at, expires_at
- Indexes: (story_id, status), (product_id, status), (status, expires_at)
- Back-relations: User.asked_questions (ClaudeQuestionAsker),
  User.answered_questions (ClaudeQuestionAnswerer), Story.claude_questions,
  Task.claude_questions, Product.claude_questions

Migratie (20260427224849_add_claude_questions):
- Prisma-gegenereerde DDL voor claude_questions + indexes + 5 FK's
- Toegevoegde notify_question_change() functie + claude_questions_notify trigger
  op AFTER INSERT/UPDATE
- Emit op BESTAANDE scrum4me_changes-channel met entity:'question' (i.t.t. M10
  dat eigen scrum4me_pairing-channel kreeg) — solo-route in ST-1104 moet
  entity='question' wegfilteren om regressie op solo-board te voorkomen
- Trigger leest story.assignee_id voor "wacht op jou"-emphase in payload
- DELETE niet ondersteund — questions gaan naar answered/cancelled/expired

Verification: Node pg-client roundtrip via DATABASE_URL toonde correcte payloads
bij INSERT (op=I, status=open) en UPDATE (op=U, status=answered) met alle FK-IDs
en assignee_id correct uit story-join.

Volgende stap M11: ST-1102 — vier MCP-tools in scrum4me-mcp-repo
(ask_user_question, get_question_answer, list_open_questions, cancel_question).

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

* feat(ST-1103): add answerQuestion server action

actions/questions.ts:
- answerQuestion(questionId, answer) — auth + Zod + demo-blok + access-check
  via productAccessFilter (anyone met product-membership mag antwoorden,
  consistent met Scrum self-organizing — niet alleen story-assignee)
- Atomic prisma.claudeQuestion.updateMany WHERE id + status='open' +
  expires_at>now → status='answered'; concurrent dubbele submit: één wint
  (count=1), rest count=0 met disambiguatie via second findFirst
- revalidatePath('/', 'layout') refresh't NavBar bell-count voor SSR-paths;
  realtime updates voor andere clients gaan via SSE in ST-1104/1105
- Begrijpelijke NL-foutmeldingen voor elk faalpad

Tests __tests__/actions/questions.test.ts (6 cases):
- happy: status update + revalidatePath called
- demo-block: error + geen DB-call + geen revalidate
- geen access: error + geen update
- al-answered: race-error 'is al answered'
- expired: race-error 'is verlopen'
- lege answer: Zod-validatie

Quality gates: lint 0 errors, tsc clean, vitest 145/145 (17 files).

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

* feat(ST-1104): add user-scoped /api/realtime/notifications + filter solo-route

Twee delen:

1. Solo-route filter (1-regel-fix in app/api/realtime/solo/route.ts):
   - NotifyPayload uitgebreid met entity:'question'
   - shouldEmit returnt direct false bij entity='question'
   Voorkomt dat solo-clients M11 question-events ontvangen (geen lekkage naar
   het Solo-bord; geen onnodig netwerk-verkeer; loose coupling tussen features).

2. Nieuwe SSE-route app/api/realtime/notifications/route.ts:
   - User-scoped (geen ?product_id=); query alle accessible product-IDs één keer
     bij connect via productAccessFilter
   - LISTEN scrum4me_changes; filter entity='question' && product_id ∈ accessible
   - Initial-state-event NA LISTEN actief (race-fix conform M10 ST-1004):
     query open vragen voor deze user's accessible products, stuur als event:state
     met summary (id, story_code/title, assignee_id, question, options, expires_at)
   - Hergebruikt het pg.Client + ReadableStream + heartbeat 25s + hard-close 240s +
     abort-cleanup-pattern uit solo-route

Tests __tests__/api/notifications-stream.test.ts:
- 401 zonder iron-session cookie (en geen DB-call)
- Solo-route filter wordt visueel/E2E gedekt in ST-1108-acceptatie

Quality gates: lint 0 errors, tsc clean, vitest 146/146 (18 files).

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

* feat(ST-1105): add NavBar bell + sheet + answer-modal + Zustand store + SSE hook

UI-volledig voor de Claude vraag-antwoord-flow (M11). Bel-icon links van avatar
in NavBar; klik opent slide-over rechts met openstaande vragen; klik op een vraag
opent een modal voor antwoord. Story-assignee = current user krijgt visuele
"voor jou"-emphase met primary-container accent en error-color badge-ring.

Bestanden:
- stores/notifications-store.ts — Zustand store met init/upsert/remove +
  openCount/forYouCount selectors (vereenvoudigd vs solo-store: geen pendingOps,
  geen optimistic-echo-onderdrukking)
- lib/realtime/use-notifications-realtime.ts — EventSource hook met state-
  event en message-event handling, exponential-backoff reconnect, Page
  Visibility pause-resume
- components/notifications/notifications-bridge.tsx — Server Component die
  initial open-questions fetcht via productAccessFilter
- components/notifications/notifications-realtime-mount.tsx — tiny client
  island dat de store hydrateert + de hook activeert
- components/notifications/notifications-sheet.tsx — shadcn Sheet met item-
  lijst, "voor jou"-accent voor assignee-vragen, lege staat
- components/notifications/answer-modal.tsx — Dialog met options-radio of
  free-text Textarea (max 4000), char-counter, demo-blok via Tooltip; bij
  succes optimistisch remove + sheet blijft open zodat meerdere vragen
  achter elkaar te beantwoorden zijn
- components/shared/notifications-bell.tsx — Bell-icon met badge (count >9 → "9+"),
  ring-accent als forYouCount > 0, ARIA-label voor screenreaders

Wiring:
- components/shared/nav-bar.tsx — <NotificationsBell /> rechts naast <UserMenu>
- app/(app)/layout.tsx — <NotificationsBridge /> naast <SoloRealtimeBridge />,
  user.id (server-side) als prop

base-ui-aanpassingen: SheetTrigger/TooltipTrigger gebruiken render-prop ipv
asChild (geen Radix).

Quality gates: lint 0 errors, tsc clean, vitest 146/146, npm run build groen.

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

* test(ST-1106): add cross-product access-isolation test for notifications SSE

Demo-policy + assignee-emphase zaten al in eerdere stories:
- answerQuestion demo-blok in actions/questions.test.ts (ST-1103)
- AnswerModal demo-tooltip in components/notifications/answer-modal.tsx (ST-1105)
- requireWriteAccess in MCP write-tools (ST-1102)

Deze story voegt expliciet een access-isolation-test toe op de notifications-
SSE-route: productAccessFilter wordt met de echte userId aangeroepen, en
prisma.product.findMany filter't op archived=false + user_id-scope. Dat
garandeert dat een gebruiker geen question-events ontvangt voor producten waar
hij geen membership op heeft.

Story-assignee-emphase blijft visueel-only (NotificationsBell ring-accent +
Sheet primary-container) — toegang werkt product-membership-breed zodat een
team-lid kan invallen als de assignee niet beschikbaar is.

Quality gates: lint 0 errors, tsc clean, vitest 147/147 (was 146).

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

* feat(ST-1107): add Vercel cron expire-questions (+ M10 pairing cleanup)

POST /api/cron/expire-questions:
- Auth via Authorization: Bearer ${CRON_SECRET} (Vercel injecteert dit
  automatisch wanneer de env-var op de project-omgeving staat); 401 als secret
  niet matcht of niet is gezet (faal-veilig — geen open endpoint in dev)
- updateMany op claude_questions WHERE status='open' AND expires_at<now →
  'expired'
- Bonus: zelfde route ruimt M10 login_pairings op (status='pending' AND
  expires_at<now → 'cancelled'). Eén cron-job is goedkoper qua Vercel-budget
  en houdt cleanup-strategie centraal — opvolg-actie uit M10 dat geparkeerd was.

Config:
- vercel.json: crons-entry { path: '/api/cron/expire-questions', schedule: '0 */6 * * *' } (4x/dag)
- lib/env.ts: CRON_SECRET als optional in Zod-schema
- .env.example: documentatie + openssl rand-tip

Tests __tests__/api/cron-expire-questions.test.ts (4 cases):
- 401 zonder Authorization-header
- 401 met verkeerde secret
- 401 als CRON_SECRET niet is gezet (faal-veilig)
- 200 met juiste secret: response { expired_questions, expired_pairings, ran_at }
  + beide updateMany WHERE/data correct

Quality gates: lint 0 errors, tsc clean, vitest 151/151.

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

* docs(ST-1108): document M11 question-channel — API + architecture + pattern

docs/API.md — twee nieuwe secties:
- 'Notifications' met /api/realtime/notifications SSE-endpoint (event-shapes,
  filter-rules, voorbeeld)
- 'Cron — Expire questions' met /api/cron/expire-questions (Bearer-auth,
  schedule, response-shape, manual curl)

docs/scrum4me-architecture.md — nieuw hoofdstuk 'Vraag-antwoord-kanaal Claude
↔ user' tussen QR-pairing-flow en Projectstructuur:
- Mermaid sequence-diagram (Claude → DB → trigger → SSE → user → answer →
  trigger → Claude polls)
- Threat-model-tabel (race, demo-misbruik, cross-product leak, cron-misbruik,
  growth, log-leakage)
- Subsectie 'Waarom hergebruik scrum4me_changes-kanaal' met trade-off vs M10's
  eigen-kanaal-aanpak

docs/patterns/claude-question-channel.md — herbruikbaar pattern 'Bidirectionele
async-comms tussen MCP-agent en interactieve user' met de vier eindpunten,
vier security-uitgangspunten, channel-strategie-tabel, TTL-richtlijn, en
sjabloon-bestanden per laag (DB / server / client / MCP-tools).

CLAUDE.md — extra rij in Implementatiepatronen-tabel die naar het nieuwe
pattern-doc verwijst.

Acceptatie 6 scenario's:
1. Sync happy path (MCP wait_seconds + UI submit) — handmatig getest tijdens
   ST-1105 acceptance-loop met de q-test injection
2. Async happy path — gedekt door get_question_answer-tool in ST-1102 +
   list_open_questions
3. Demo-block — actions/questions.test.ts (case 2: demo-user) + AnswerModal
   tooltip (visueel)
4. Access-isolation — notifications-stream.test.ts (case 'access-isolation')
5. Expiry — cron-expire-questions.test.ts (case '200 met juiste secret')
6. Race — actions/questions.test.ts (case 'al-answered' via atomic updateMany)

Quality gates: lint 0 errors, tsc clean, vitest 151/151 (19 files), npm run
build groen.

M11 is hiermee feature-compleet. feat/M11-claude-questions heeft 12 commits
lokaal, klaar voor user-acceptatie en PR.

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

* fix(ST-1107): cron schedule daily — Vercel Hobby allows only 1 run/day

Vercel deploy faalde met:
> Hobby accounts are limited to daily cron jobs.
> This cron expression (0 */6 * * *) would run more than once per day.

Schedule van 4×/dag (0 */6 * * *) naar 1×/dag (0 4 * * * — 04:00 UTC, rustig
tijdstip). Functioneel acceptabel: ClaudeQuestion TTL is 24u, dus daily
cleanup pakt alles dat in de afgelopen 24u verlopen is. Login-pairings TTL
is 2 min — die zijn al onbruikbaar zodra ze expiren, cron is alleen voor
status-housekeeping.

Schedule-referenties consistent bijgewerkt in docs (API.md, architecture,
backlog M11-sectie, plan-doc, pattern-doc) + comment in route.ts. Vermelding
overal dat dit een Hobby-plan-beperking is en Pro fijnmaziger ondersteunt.

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

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-29 11:38:23 +02:00

24 KiB
Raw Blame History

M11 — Claude vraagt, gebruiker antwoordt

Persistent vraag-antwoord-kanaal tussen Claude Code (via MCP) en de actieve Scrum4Me-gebruiker. Claude schrijft een vraag naar claude_questions als hij vastloopt op een keuze; een Postgres-trigger emit op het bestaande scrum4me_changes-kanaal; de app toont een notificatie-badge; iedereen met product-toegang kan antwoorden; Claude leest het antwoord (sync via polling of in latere sessie via get_question_answer) en gaat door.

Eerste concrete uitwerking van strategische richting B (verdiepen van de unieke AI-driven dev-flow).

Backlog-entries: zie scrum4me-backlog.md § M11 (op te leveren in ST-1108).

Beveiligingsuitgangspunten:

  • Atomic answer via updateMany WHERE status='open' — concurrent dubbele submit kan niet
  • Demo-blok op ask_user_question (MCP) en answerQuestion (Server Action)
  • Access-check via productAccessFilter in DB-query én SSE-filter; vraag-tekst en antwoord komen pas via een aparte authenticated query
  • Cron-endpoint beveiligd via Authorization: Bearer ${CRON_SECRET}
  • Logging: alleen question_id, nooit vraag/antwoord-tekst (kan gevoelige info bevatten)

Gekozen kaders (uit overleg):

  • Sync-model: default async — ask_user_question retourneert direct met question_id; optionele wait_seconds (max 600) voor polling tot het antwoord er is
  • Answer-policy: iedereen met product-toegang mag antwoorden; story-assignee krijgt visuele "wacht op jou"-emphase
  • Realtime: hergebruik scrum4me_changes-kanaal (uitgebreid met entity: 'question'); aparte user-scoped SSE-route /api/realtime/notifications zodat solo-board-SSE product-scoped blijft

ST-1101 — ClaudeQuestion schema + Postgres-trigger

Bestanden

  • prisma/schema.prisma — model ClaudeQuestion + relations op User/Story/Task/Product
  • prisma/migrations/<ts>_add_claude_questions/migration.sql — table-DDL + trigger
  • vendor/scrum4me-submodule in scrum4me-mcp — schema-sync ná merge

Stappen

  1. Schema-uitbreiding:

    model ClaudeQuestion {
      id           String    @id @default(cuid())
      story_id     String
      story        Story     @relation(fields: [story_id], references: [id], onDelete: Cascade)
      task_id      String?
      task         Task?     @relation(fields: [task_id], references: [id], onDelete: SetNull)
      product_id   String    // gedenormaliseerd voor SSE-filter
      product      Product   @relation(fields: [product_id], references: [id], onDelete: Cascade)
      asked_by     String
      asker        User      @relation("ClaudeQuestionAsker", fields: [asked_by], references: [id])
      question     String    @db.Text
      options      Json?     // string[] voor multi-choice; null voor free-text
      status       String    // 'open' | 'answered' | 'cancelled' | 'expired'
      answer       String?   @db.Text
      answered_by  String?
      answerer     User?     @relation("ClaudeQuestionAnswerer", fields: [answered_by], references: [id])
      answered_at  DateTime?
      created_at   DateTime  @default(now())
      expires_at   DateTime
    
      @@index([story_id, status])
      @@index([product_id, status])
      @@index([status, expires_at])
      @@map("claude_questions")
    }
    

    Plus op User: asked_questions ClaudeQuestion[] @relation("ClaudeQuestionAsker") en answered_questions ClaudeQuestion[] @relation("ClaudeQuestionAnswerer").

  2. Migratie-SQL voegt naast tabel + indexes ook trigger toe (mirror van notify_pairing_change uit M10 ST-1001):

    CREATE OR REPLACE FUNCTION notify_question_change() RETURNS trigger AS $$
    DECLARE
      story_row record;
      payload jsonb;
    BEGIN
      SELECT assignee_id INTO story_row FROM stories WHERE id = NEW.story_id;
      payload := jsonb_build_object(
        'op', CASE TG_OP WHEN 'INSERT' THEN 'I' ELSE 'U' END,
        'entity', 'question',
        'id', NEW.id,
        'product_id', NEW.product_id,
        'story_id', NEW.story_id,
        'task_id', NEW.task_id,
        'assignee_id', story_row.assignee_id,
        'status', NEW.status
      );
      PERFORM pg_notify('scrum4me_changes', payload::text);
      RETURN NEW;
    END;
    $$ LANGUAGE plpgsql;
    
    CREATE TRIGGER claude_questions_notify
      AFTER INSERT OR UPDATE ON claude_questions
      FOR EACH ROW EXECUTE FUNCTION notify_question_change();
    
  3. npx prisma migrate dev --name add_claude_questions

Aandachtspunten

  • entity: 'question' is een nieuwe waarde naast bestaande 'task'/'story'. Solo-route in M8 filter't via payload.entity — moet 'question'-events expliciet wegfilteren (niet emitten naar solo-clients)
  • product_id op de question is gedenormaliseerd uit story.product_id — voorkomt extra join in SSE-filter (zelfde keuze als story.product_id in M3)
  • vendor/scrum4me-submodule sync vereist na merge (drift-check trig_015FFUnxjz9WMuhhWNGBQKFD)

Verificatie

  • npx prisma migrate dev slaagt; npx prisma validate clean
  • psql $DIRECT_URL -c "LISTEN scrum4me_changes;" toont payload met entity: 'question' bij INSERT
  • Bestaande solo-flow nog steeds werkend (regressie-check)

ST-1102 — MCP-tools (in scrum4me-mcp-repo)

Bestanden

  • scrum4me-mcp/src/tools/ask-user-question.ts — nieuw
  • scrum4me-mcp/src/tools/get-question-answer.ts — nieuw
  • scrum4me-mcp/src/tools/list-open-questions.ts — nieuw
  • scrum4me-mcp/src/tools/cancel-question.ts — nieuw
  • scrum4me-mcp/src/index.ts — register de vier tools
  • scrum4me-mcp/scripts/smoke-test.ts — uitbreiden met question-roundtrip
  • scrum4me-mcp/README.md — tool-tabel uitbreiden

Stappen

  1. ask_user_question (write-tool, sjabloon create-todo.ts):

    • Input: { story_id, question, options?, task_id?, wait_seconds? }wait_seconds 0600 (Zod .min(0).max(600))
    • requireWriteAccess (demo-blok)
    • Access-check: userCanAccessProduct(story.product_id, auth.userId)
    • Insert met expires_at = now() + 24h, status = 'open'
    • Als wait_seconds === 0 (default): return { question_id, status: 'open' }
    • Als wait_seconds > 0: poll elke 2s tot status !== 'open' of timeout. Bij answered: return { question_id, status, answer, answered_by, answered_at }. Bij timeout: return { question_id, status: 'pending' } zodat Claude met get_question_answer later kan ophalen
    • Polling-implementatie: setInterval met Promise en abort-signal voor schone cleanup
  2. get_question_answer (read-tool):

    • Input: { question_id }
    • Access-check via userCanAccessProduct(question.product_id, auth.userId)
    • Output: full row (status, answer, answered_by, answered_at, expires_at)
  3. list_open_questions (read-tool):

    • Input: { story_id? } (optionele filter)
    • Output: array van eigen vragen (asked_by === auth.userId) met status open of answered, max 50, geordend op created_at desc
    • Bedoeld voor Claude om bij begin van een sessie te zien of eerdere vragen inmiddels beantwoord zijn
  4. cancel_question (write-tool):

    • Input: { question_id }
    • Alleen de asker mag cancelen; requireWriteAccess voor demo-blok
    • Atomic updateMany WHERE id=… AND status='open' AND asked_by=…
    • Bedoeld voor wanneer Claude zelf de oplossing vindt en de vraag overbodig wordt
  5. Smoke-test in scripts/smoke-test.ts: ask_user_question met wait_seconds=5 + parallel answerQuestion (via REST of direct DB-write) → verifieer dat de tool het antwoord retourneert binnen het venster

Aandachtspunten

  • wait_seconds polling moet aborten als de MCP-cliënt disconnect (signal-check) — anders blijft de Node-process hangen op een dood socket
  • options-veld accepteert string-array; in zod als z.array(z.string()).optional()
  • Als wait_seconds > 300 raakt 'm Vercel-deploy onmogelijk (Vercel-functies cap op 300s) — maar de MCP-server draait lokaal bij Claude Code, dus 600s mag

Verificatie

  • MCP Inspector toont 4 nieuwe tools (totaal 13)
  • Smoke-test groen: ask + answer roundtrip binnen 5s
  • Demo-token op ask_user_question of cancel_question geeft PERMISSION_DENIED
  • tsc --noEmit clean op scrum4me-mcp

ST-1103 — Server Actions voor de browser-UI

Bestanden

  • actions/questions.ts — nieuw
  • __tests__/actions/questions.test.ts — nieuw

Stappen

  1. answerQuestion(questionId, answer) (volgt docs/patterns/server-action.md):

    • getSession + requireUser; demo-blok via if (session.isDemo) return { ok: false, error: 'Niet beschikbaar in demo-modus' }
    • Zod-input: { questionId: cuid, answer: string.min(1).max(4000) }
    • Lookup question + access-check via userCanAccessProduct(question.product_id, userId)
    • Atomic updateMany WHERE id=… AND status='open' AND expires_at > now() met data: { status: 'answered', answer, answered_by: userId, answered_at: now }
    • Bij count === 0: disambigueer (al-answered → 'al beantwoord', expired → 'verlopen', geen access → 'geen toegang')
    • revalidatePath('/', 'layout') zodat badge-count overal updatet
  2. cancelQuestionByAnswerer(questionId)uitgesteld naar v2. Voor v1 alleen Claude (asker) kan annuleren via MCP. Als de UI later een dismiss-functie krijgt, komt het hier.

  3. Tests __tests__/actions/questions.test.ts (6 cases):

    • happy answer → status='answered', revalidatePath aangeroepen
    • demo-user → error + geen DB-write
    • user zonder product-access → error
    • already-answered → race-error (updateMany count=0 met status='answered' fallback)
    • expired → error
    • empty answer → Zod-validatie

Aandachtspunten

  • revalidatePath('/', 'layout') is correct (zelfde keuze als M9 setActiveProductAction) — badge zit in app-layout
  • Geen revalidatePath op /sprint of /solo nodig — die zien de question niet
  • Bij multi-tab: na answer in tab-1 verdwijnt het item in tab-2 via SSE-event, niet via revalidate. revalidate is voor de SSR-render-na-navigatie

Verificatie

  • npm test 6/6 voor questions
  • Handmatig: open vraag in browser, antwoord, badge-count zakt met 1
  • Demo-test: log in als demo, klik antwoord → toast "Niet beschikbaar in demo-modus"

ST-1104 — User-scoped SSE-route /api/realtime/notifications

Bestanden

  • app/api/realtime/notifications/route.ts — nieuw
  • app/api/realtime/solo/route.ts — uitbreiden om entity: 'question' te filteren (anders krijgt solo-client question-events ongewenst door)
  • __tests__/api/notifications-stream.test.ts — nieuw (auth-cases)

Stappen

  1. Route Handler — sjabloon uit app/api/realtime/solo/route.ts:

    • runtime: 'nodejs', maxDuration: 300, dynamic: 'force-dynamic'
    • Auth via iron-session cookie; 401 zonder
    • User-scoped (geen ?product_id=-param). Bij connect: query productAccessFilter(userId) om alle accessible product-IDs te krijgen
    • LISTEN op scrum4me_changes; filter:
      • payload.entity === 'question' (anders skip)
      • payload.product_id IN accessibleProductIds
    • Initial-state-event direct na connect, na LISTEN actief: query claude_questions met status='open' voor deze user's accessible products. Stuur als event: state\ndata: [{...question-summary...}]. Voorkomt race tussen connect en LISTEN (zelfde fix als M10 ST-1004)
    • Auto-close bij hard-close 240s; client herconnect
  2. Solo-route bijwerken: in shouldEmit toevoegen if (payload.entity === 'question') return false

  3. Tests (auth-paden, full-stream blijft handmatig):

    • 401 zonder iron-session cookie
    • Bij connect met sessie: list van accessible products correct gefilterd
    • Question-event op een product zonder access → niet doorgegeven

Aandachtspunten

  • Twee parallelle SSE-streams in browser (solo-route op product-pagina + notifications-route in app-layout) — netwerk-overhead aanvaardbaar; Vercel rekent per-actieve-functie ongeacht aantal streams
  • Initial-state event content: een kleine summary (id, story_code, question, options?) per open vraag — voorkomt dat de bridge eerst een aparte fetch moet doen voor de initial badge-count
  • Path expliciet maken in een client useNotificationsRealtime-hook (volgt useSoloRealtime-pattern)

Verificatie

  • curl -N --cookie session-jar /api/realtime/notifications blijft openstaan, levert event: state direct
  • INSERT op claude_questions voor een toegankelijk product → event binnen 1s
  • INSERT voor een ontoegankelijk product → geen event
  • Solo-route op /api/realtime/solo?product_id=… levert geen question-events meer

ST-1105 — Notifications-UI (Bell + Sheet + Answer-modal)

Bestanden

  • components/shared/notifications-bell.tsx — nieuw
  • components/notifications/notifications-sheet.tsx — nieuw
  • components/notifications/answer-modal.tsx — nieuw
  • components/notifications/notifications-bridge.tsx — nieuw, hookt SSE-listener aan store
  • stores/notifications-store.ts — nieuw
  • lib/realtime/use-notifications-realtime.ts — nieuw
  • components/shared/nav-bar.tsx<NotificationsBell /> toevoegen rechts (links van <UserMenu>)
  • app/(app)/layout.tsx<NotificationsBridge /> mounten (analoog aan <SoloRealtimeBridge />)

Stappen

  1. stores/notifications-store.ts — Zustand store; volgt stores/solo-store.ts-pattern:

    • State: { questions: Question[], pendingAnswerIds: Set<string> }
    • Actions: init(q[]), add(q), update(q), remove(id), optimisticAnswer(id), rollbackAnswer(id, q)
    • Selectors: openCount(userId), forYouCount(userId) (waar story-assignee = userId)
  2. lib/realtime/use-notifications-realtime.ts — analoog aan useSoloRealtime. EventSource opent op /api/realtime/notifications, dispatcht state/message-events naar store via add/update/remove. Reconnect met exponential backoff.

  3. <NotificationsBridge /> — Server Component die initial questions ophaalt en aan de store geeft via init-prop. Mount in (app)/layout.tsx zodat de bridge altijd actief is wanneer user is ingelogd.

  4. <NotificationsBell /> — Client Component:

    • Lucide Bell-icon met badge: openCount (totaal) + accent-dot als forYouCount > 0
    • Klik: setOpen(true) op de Sheet
    • Geen badge als count === 0
  5. <NotificationsSheet /> — shadcn Sheet van rechts:

    • Header: "Vragen van Claude (N)"
    • Lijst gegroepeerd op product (analoog aan M5 todo-data-table-styling), elk item: story-code + truncated title, vraag-preview (line-clamp-2), assignee-emphase als forYou, "Beantwoord" knop opent answer-modal
    • Lege staat: "Geen openstaande vragen. Lekker bezig!"
  6. <AnswerModal /> — shadcn Dialog:

    • Story-context-link bovenaan (kleine kaart)
    • Volledige vraag-tekst
    • Als options: <RadioGroup> met opties; geen vrije tekst
    • Anders: <Textarea> (max 4000 chars, char-counter)
    • "Verstuur" + "Annuleer" knoppen; submit roept answerQuestion-action via useTransition
    • Demo-modus: knop disabled met tooltip
  7. NavBar-edit: <NotificationsBell /> rechts naast de huidige avatar-trigger. Nieuwe gap-spacing in NavBar's right-section.

Aandachtspunten

  • Bell-icon en avatar moeten visueel balanceren — hoogte/padding gelijktrekken
  • MD3-tokens uit docs/scrum4me-styling.md: badge bg-error text-error-foreground voor critical-count, bg-primary voor neutraal. Geen willekeurige Tailwind-kleuren
  • Optimistic-answer in store: voor het Server Action-resultaat zet item op pending; bij error rollback met sonner-error-toast
  • Sheet-content blijft open zodat de user meerdere vragen achter elkaar kan beantwoorden (zelfde patroon als ST-358 openstaande-stories-sheet)
  • ARIA: bell-icon heeft aria-label="Notificaties — N open vragen", badge role="status"

Verificatie

  • Bell verschijnt in NavBar links van avatar; badge count = open question count
  • Klik opent Sheet; lijst rendert correct met assignee-emphase
  • Submit schiet event door — in tweede tab van zelfde user verdwijnt item binnen 1-2s
  • Demo-modus: Sheet rendert, Modal opent, "Verstuur" disabled
  • E2E-flow: Claude ask_user_question → bell-badge wordt 1 → klik → modal → submit → badge wordt 0 → Claude's get_question_answer levert antwoord

ST-1106 — Demo-policy + access-rules + tests

Bestanden

  • __tests__/actions/questions.test.ts — uitbreiden met access-cases (al opgezet in ST-1103)
  • __tests__/api/notifications-stream.test.ts — access-cases
  • Documentatie-aanpassingen in actions/questions.ts en SSE-route met expliciete demo-blok-comment

Stappen

  1. Verifieer dat requireProductWriter alle Server-Action-mutaties al dekt (zou moeten — uit M3.5)
  2. Voeg expliciete demo-test toe: demo-user opent answer-modal → Verstuur disabled met tooltip
  3. Voeg access-test toe: user-A heeft geen access tot product van user-B → user-A's notification-stream krijgt geen events voor user-B's questions

Aandachtspunten

  • Story-assignee-emphase is alleen visueel — toegang is product-membership-breed. Dit is bewust: als de assignee niet beschikbaar is moet een andere member kunnen invallen
  • Demo kan een vraag wel lezen (transparantie over hoe de feature werkt) — alleen niet beantwoorden

Verificatie

  • 6+ tests groen (al gedekt in ST-1103/1104)
  • Handmatige cross-product-test met 2 users + 2 producten

ST-1107 — Auto-expire + Vercel cron-cleanup

Bestanden

  • app/api/cron/expire-questions/route.ts — nieuw
  • vercel.tscrons-entry toevoegen
  • lib/env.tsCRON_SECRET toevoegen aan Zod-schema
  • .env.exampleCRON_SECRET documenteren

Stappen

  1. Cron-handler:

    export const runtime = 'nodejs'
    
    export async function POST(request: Request) {
      const auth = request.headers.get('authorization')
      if (auth !== `Bearer ${process.env.CRON_SECRET}`) {
        return Response.json({ error: 'Unauthorized' }, { status: 401 })
      }
    
      const result = await prisma.claudeQuestion.updateMany({
        where: { status: 'open', expires_at: { lt: new Date() } },
        data: { status: 'expired' },
      })
      // Optioneel: ook M10 login_pairings cleanup hier (eerder geparkeerd)
      return Response.json({ expired: result.count })
    }
    
  2. vercel.ts:

    export const config: VercelConfig = {
      // ... bestaande config
      crons: [{ path: '/api/cron/expire-questions', schedule: '0 4 * * *' }],
    }
    
  3. Documenteer in .env.example: CRON_SECRET=<openssl rand -base64 32>

Aandachtspunten

  • Vercel cron POST't standaard zonder body; auth is alleen via header
  • Op Hobby-plan zijn crons beperkt — check budget. M11 cron is 4x/dag, prima
  • Cron-trigger update't claude_questions → trigger fired → SSE-events → UI updates badge real-time. Geen extra plumbing nodig

Verificatie

  • Handmatig: curl -X POST -H "Authorization: Bearer ${CRON_SECRET}" /api/cron/expire-questions met een vraag waar expires_at < now → response {expired: 1}, vraag verdwijnt uit notifications
  • Onbevoegde call zonder secret → 401
  • Vercel dashboard toont cron-config na deploy

ST-1108 — Documentatie + acceptatietest

Bestanden

  • docs/API.md — secties "SSE — Notifications" + "Cron — Expire questions"
  • docs/scrum4me-architecture.md — sectie "Vraag-antwoord-kanaal" met sequence-diagram
  • docs/patterns/claude-question-channel.md — herbruikbaar pattern-doc
  • docs/scrum4me-backlog.md — M11-tabel-rij + M11-sectie
  • prisma/seed-data/parse-backlog.tsM11: 'ACTIVE', M10: 'COMPLETED', M3.5: 'COMPLETED'
  • CLAUDE.md — pattern-doc verwijzing in Implementatiepatronen-tabel

Stappen

  1. Backlog-tabel-rij + M11-sectie in docs/scrum4me-backlog.md (mirror M10-format met Implementatieplan: verwijzing naar dit doc)

  2. docs/scrum4me-architecture.md § "Vraag-antwoord-kanaal":

    • Mermaid sequence-diagram: Claude → MCP → DB → trigger → SSE → user → Server Action → DB → trigger → polling-tool
    • Threat-model-tabel (replay, demo-block, access-leak, expiry, race)
    • "Waarom hergebruik scrum4me_changes-kanaal" sub-sectie
  3. docs/patterns/claude-question-channel.md — generiek pattern voor toekomstige bidirectionele async-communicatie tussen MCP-agents en interactieve users

  4. Parser-flip: M11 wordt nieuwe ACTIVE-milestone, M10 → COMPLETED. (Zelfde patroon als bij M10-start: chore-commit met vlag-flip + re-seed.)

  5. Acceptatie-scenario's (zes, deels door unit-tests gedekt):

    1. Sync happy path: Claude ask_user_question(wait_seconds=300) → user antwoordt binnen 30s → MCP-tool retourneert het antwoord
    2. Async happy path: ask_user_question(wait_seconds=0) → tool returnt direct → user antwoordt later → Claude get_question_answer → ziet antwoord
    3. Demo-block: demo-user opent vraag → kan inhoud lezen → "Verstuur" disabled (UI + Server Action )
    4. Access-isolation: vraag op product zonder access → onzichtbaar in andere user's notifications-bell (SSE-filter )
    5. Expiry: vraag met expires_at < now → na cron-run niet meer in badge-count
    6. Race: concurrent answer-poging op al-beantwoorde vraag → schone foutmelding (atomic updateMany count=0 )

Aandachtspunten

  • Acceptatie-scenario's 1-2 zijn handmatig (full Claude+browser cyclus); 3-6 worden in unit-tests vastgelegd
  • Pattern-doc moet ook beschrijven wanneer NIET te gebruiken (bv. wanneer een gewone API-call met sessie volstaat)

Verificatie

  • Alle docs gepubliceerd in repo
  • Backlog-parser-self-test: npx tsx prisma/seed-data/parse-backlog.ts toont M11 met priority=4 sprint=ACTIVE
  • 6/6 acceptatie-scenario's groen
  • npm run lint && npx tsc --noEmit && npm test && npm run build clean
  • vendor/scrum4me-submodule sync in scrum4me-mcp na merge

Branch- en commit-strategie

Per CLAUDE.md → Branch & PR Strategy:

  • Eén branch op Scrum4Me: feat/M11-claude-questions afgesplitst van main ná M10-merge
  • Aparte branch op scrum4me-mcp: feat/M11-question-tools
  • Commits chronologisch per stap met ST-code in titel:
chore(M11): swap demo-active sprint from M10 to M11
feat(ST-1101): add ClaudeQuestion model + notify_question_change trigger
feat(ST-1102): add 4 MCP question tools (in scrum4me-mcp)
feat(ST-1103): add answerQuestion server action
feat(ST-1104): add /api/realtime/notifications user-scoped SSE
feat(ST-1104): filter entity='question' from solo-realtime stream
feat(ST-1105): add Zustand notifications-store + realtime hook
feat(ST-1105): add NotificationsBridge in app layout
feat(ST-1105): add NotificationsBell + Sheet + AnswerModal
chore(ST-1107): add CRON_SECRET to env schema
feat(ST-1107): add /api/cron/expire-questions handler
feat(ST-1107): wire vercel.ts cron entry
docs(ST-1108): document notifications SSE + cron in API.md
docs(ST-1108): add vraag-antwoord-kanaal flow to architecture
docs(ST-1108): add claude-question-channel pattern doc
chore(ST-1108): backlog M11 + parser ACTIVE-flip

Push + PR pas na handmatige acceptatie van scenario 1 (sync happy path) + 3 (demo-block) op localhost.

MCP-PR pas mergen ná Scrum4Me-PR + submodule-sync — anders wijzen MCP-tools naar een schema-tabel die op main nog niet bestaat.


Reseed-stap (eenmalig vóór ST-1101-implementatie)

Backlog-markdown moet eerst de M11-stories bevatten en de parser moet M11 als ACTIVE-milestone kennen voordat mcp__scrum4me__get_claude_context ze als next-story kan teruggeven. Workflow:

  1. Doe ST-1108 backlog-edit + parser-flip eerst (commit chore(M11): swap demo-active sprint from M10 to M11 + de backlog-uitbreiding)
  2. npm run seed — re-seed met M11=ACTIVE
  3. mcp__scrum4me__get_claude_context levert nu ST-1101 als next-story
  4. Verder met ST-1101-implementatie

Let op: seed wist user-data. Doe dit op een dev-DB.


Buiten scope (volgende milestones)

  • AI-suggested antwoorden — Claude leest de codebase en stelt 3 mogelijke antwoorden voor; user kiest. Vereist tweede LLM-call per vraag.
  • Mobile-push notifications — bouwt op M10 paired-flow + service-worker. v3.
  • Question-templates — "ambiguous-naming"-vraag, "missing-test-case"-vraag etc. voor consistentie.
  • Threading — vervolgvraag op een antwoord. v1 is single-shot Q&A.
  • File-uploads als antwoord — bv. een screenshot.
  • Stats/dashboard — gemiddelde antwoord-tijd, meest-gestelde-vraagsoorten.
  • Dismiss-per-user — een member negeert een vraag voor zichzelf zonder 'm te beantwoorden.