docs(PBI-67/ST-1301): runbook + CLAUDE.md updates voor model/mode-selectie

T-794: Nieuwe runbook docs/runbooks/job-model-selection.md met override-cascade, kind-default-matrix, override-voorbeelden, auditspoor en cost-attribution-formule. 107 regels. T-795: CLAUDE.md hardstop-bullet voor 'Model/mode per ClaudeJob' (verwijst naar nieuwe runbook) + patterns-quickref-rij voor job-config resolver. CLAUDE.md blijft 139 regels (≤ 150). T-796: docs:check-links groen — 108 files, geen broken links. Twee externe-repo verwijzingen (scrum4me-mcp/...) ge-de-linked tot plain text omdat de check-links script de zustertree niet traverseert; de referenties blijven leesbaar. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-08 11:18:03 +02:00 · 2026-05-08 11:18:03 +02:00 · 4b7b1429c8
commit 4b7b1429c8
parent d0bebda3ac
4 changed files with 111 additions and 1 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -60,6 +60,7 @@ Volledige MCP-tool documentatie: [docs/runbooks/mcp-integration.md](./docs/runbo
 - **Foutcodes:** 400 = parse-fout, 422 = Zod-validatie, 403 = demo-token
 - **Server/client grens:** `*-server.ts` bevat DB/node-only; nooit importeren in client component
 - **Worker/jobs:** `ClaudeJob` queue (`QUEUED → CLAIMED → RUNNING → DONE|FAILED|SKIPPED`); MCP-worker claimt via `wait_for_job` en sluit met `update_job_status` — zie [worker-idempotency.md](./docs/runbooks/worker-idempotency.md)
+- **Model/mode per ClaudeJob:** kind-default → product → job-snapshot → `task.requires_opus`. Resolver in `scrum4me-mcp/src/lib/job-config.ts` (en gespiegeld in `lib/job-config.ts`) — zie [job-model-selection.md](./docs/runbooks/job-model-selection.md)
 - **Deployment:** `npm run verify && npm run build` vóór elke PR. Selectieve deploy-controle (labels + path-filter): zie [docs/runbooks/deploy-control.md](./docs/runbooks/deploy-control.md)

 ---
@ -96,6 +97,7 @@ Volledige MCP-tool documentatie: [docs/runbooks/mcp-integration.md](./docs/runbo
 | Realtime NOTIFY-payload | `docs/patterns/realtime-notify-payload.md` |
 | Story met UI-component | `docs/patterns/story-with-ui-component.md` |
 | Web Push | `docs/patterns/web-push.md` |
+| Job-config resolver (PBI-67) | `lib/job-config.ts` ↔ `scrum4me-mcp/src/lib/job-config.ts` |

 ---

--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@ -127,6 +127,7 @@ Auto-generated on 2026-05-08 from front-matter and headings.
 | [Branch, PR & Commit Strategy](./runbooks/branch-and-commit.md) | `runbooks/branch-and-commit.md` | active | 2026-05-03 |
 | [Deploy-controle: triggers, labels, path-filter](./runbooks/deploy-control.md) | `runbooks/deploy-control.md` | active | 2026-05-07 |
 | [Vercel Deployment](./runbooks/deploy-vercel.md) | `runbooks/deploy-vercel.md` | active | 2026-05-03 |
+| [Job-model-selectie per ClaudeJob-kind](./runbooks/job-model-selection.md) | `runbooks/job-model-selection.md` | active | 2026-05-08 |
 | [MCP Integration — Scrum4Me Tools](./runbooks/mcp-integration.md) | `runbooks/mcp-integration.md` | active | 2026-05-08 |
 | [v1.0 Smoke Test Checklist](./runbooks/v1-smoke-test.md) | `runbooks/v1-smoke-test.md` | active | 2026-05-04 |
 | [Worker idempotency & job-status protocol](./runbooks/worker-idempotency.md) | `runbooks/worker-idempotency.md` | active | 2026-05-05 |
--- a/docs/plans/job-model-selection.md
+++ b/docs/plans/job-model-selection.md
@ -144,7 +144,7 @@ End-to-end-validatie van het geheel:

 1. **`bypassPermissions` als default voor implement-kinds** (TASK_IMPLEMENTATION, SPRINT_IMPLEMENTATION). Verdedigbaar door git-worktree-isolatie. `Product.preferred_permission_mode` blijft beschikbaar als opt-in voor productie-product
 2. **Opus-cost-controle = per-task** via `Task.requires_opus`-flag. Géén product-budget, géén automatische Opus-escalatie. Ad-hoc beslissing per taak
-3. **`PLAN_CHAT` runtime bevestigd: Claude Code CLI** — `wait_for_job` ([scrum4me-mcp/src/tools/wait-for-job.ts:386](../../../scrum4me-mcp/src/tools/wait-for-job.ts)) selecteert `IDEA_GRILL`, `IDEA_MAKE_PLAN` én `PLAN_CHAT` uit dezelfde queue. Resolver past 1:1, geen aparte runtime-route
+3. **`PLAN_CHAT` runtime bevestigd: Claude Code CLI** — `wait_for_job` (`scrum4me-mcp/src/tools/wait-for-job.ts:386`) selecteert `IDEA_GRILL`, `IDEA_MAKE_PLAN` én `PLAN_CHAT` uit dezelfde queue. Resolver past 1:1, geen aparte runtime-route
 4. **`wait_for_job`-response: pure additief** (geen `protocol_version`-veld). Worker negeert onbekende velden veilig; mismatch is operationeel zichtbaar via `model_id` in token-stats. Geen multi-tenant fleet → geen versioning-overhead nodig

 ---
--- a/docs/runbooks/job-model-selection.md
+++ b/docs/runbooks/job-model-selection.md
@ -0,0 +1,107 @@
+---
+title: "Job-model-selectie per ClaudeJob-kind"
+status: active
+audience: [ai-agent, contributor]
+language: nl
+last_updated: 2026-05-08
+when_to_read: "Vóór het wijzigen van model/thinking/permission-mode-keuze of bij debugging van 'verkeerd model gebruikt'-incidents."
+---
+
+# Job-model-selectie per ClaudeJob-kind
+
+PBI-67. Per `ClaudeJob.kind` bepaalt de Scrum4Me-mcp resolver
+`scrum4me-mcp/src/lib/job-config.ts` welk Claude-model + thinking-
+budget + permission-mode + max_turns + allowed_tools de Claude Code-
+worker moet gebruiken.
+
+Dezelfde resolver staat — als één-op-één spiegel — in
+[`lib/job-config.ts`](../../lib/job-config.ts) voor de enqueue-laag,
+zodat we bij job-creatie het resolved resultaat al snapshotten in
+`ClaudeJob.requested_*`.
+
+---
+
+## Override-cascade
+
+```
+   1. Task.requires_opus = true   →  forceer claude-opus-4-7
+   2. Job.requested_*             →  snapshot bij enqueue
+   3. Product.preferred_*         →  product-brede default
+   4. KIND_DEFAULTS               →  per kind onderstaand
+```
+
+**Eerste match wint.** `max_turns` en `allowed_tools` blijven in V1
+altijd kind-default — geen product- of task-override.
+
+---
+
+## Kind-default-matrix
+
+| Kind | Model | Thinking-budget | Permission-mode | max_turns | allowed_tools |
+|---|---|---|---|---|---|
+| `IDEA_GRILL` | `claude-sonnet-4-6` | 12 000 | `plan` | 15 | Read, Grep, Glob, WebSearch, AskUserQuestion |
+| `IDEA_MAKE_PLAN` | `claude-opus-4-7` | 24 000 | `plan` | 20 | Read, Grep, Glob, WebSearch, AskUserQuestion, Write |
+| `PLAN_CHAT` | `claude-sonnet-4-6` | 6 000 | `plan` | 5 | Read, Grep, AskUserQuestion |
+| `TASK_IMPLEMENTATION` | `claude-sonnet-4-6` | 6 000 | `bypassPermissions` | 50 | (alle) |
+| `SPRINT_IMPLEMENTATION` | `claude-sonnet-4-6` | 6 000 | `bypassPermissions` | (geen) | (alle) |
+
+**`bypassPermissions`** is verdedigbaar voor de implement-kinds omdat
+elke run in een geïsoleerde git-worktree start (zie
+[branch-and-commit.md](./branch-and-commit.md)). Productie-product?
+Zet `Product.preferred_permission_mode = 'acceptEdits'`.
+
+---
+
+## Wanneer overrul je een default?
+
+| Scenario | Wijzig op | Voorbeeld |
+|---|---|---|
+| Cross-file refactor of architectuurkeuze in TASK_IMPLEMENTATION | `Task.requires_opus = true` | Een PBI met "rip out auth middleware" |
+| Klant wil budget-control op een product | `Product.preferred_model = claude-sonnet-4-6` | Side-product met Haiku-only-budget |
+| Productie-product zonder bypassPermissions | `Product.preferred_permission_mode = 'acceptEdits'` | Klant-facing repo waar elke wijziging review nodig heeft |
+| Ad-hoc: Opus voor één specifieke story-job | `ClaudeJob.requested_model = claude-opus-4-7` (handmatige UPDATE) | Nood-debug van prod-incident |
+| Geen thinking voor een PLAN_CHAT (snelle reactie) | `Product.thinking_budget_default = 0` (alle kinds in dat product) | Demo-product |
+
+---
+
+## Auditspoor
+
+| Kolom | Wat | Wanneer ingevuld |
+|---|---|---|
+| `requested_model` | Resolved model op enqueue-tijd | `actions/*` enqueue-laag via `lib/job-config-snapshot.ts` |
+| `requested_thinking_budget` | Resolved budget op enqueue-tijd | idem |
+| `requested_permission_mode` | Resolved permission-mode | idem |
+| `model_id` | Werkelijk gebruikt model | `update_job_status` na worker-run |
+| `actual_thinking_tokens` | Werkelijk verbruikte thinking-tokens | idem |
+
+Verschillen tussen `requested_model` en `model_id` zijn zichtbaar in
+**admin → Jobs → Kosten** (rood-gemarkeerd modelveld + tooltip).
+Meestal duidt dat op een worker die de CLI-flag niet doorgaf —
+controleer de worker-script tegen de flag-tabel in
+[worker-idempotency.md](./worker-idempotency.md#config-doorgeven-aan-claude-code-pbi-67).
+
+---
+
+## Cost-attribution
+
+Thinking-tokens worden bij Anthropic-billing gerekend tegen de
+input-rate van het model. `lib/insights/token-stats.ts` en
+`lib/insights/token-history.ts` doen hetzelfde:
+
+```sql
+COALESCE(cj.actual_thinking_tokens, 0) * mp.input_price_per_1m / 1000000.0
+```
+
+Voor per-kind aggregatie binnen een sprint: gebruik
+`getTokenStatsByKind(userId, sprintId)`.
+
+---
+
+## Referenties
+
+- Plan: [docs/plans/job-model-selection.md](../plans/job-model-selection.md)
+- Resolver (MCP): `scrum4me-mcp/src/lib/job-config.ts`
+- Resolver (main): `lib/job-config.ts`
+- Snapshot-helper: `lib/job-config-snapshot.ts`
+- Worker-flag-mapping: [worker-idempotency.md](./worker-idempotency.md#config-doorgeven-aan-claude-code-pbi-67)
+- Schema: `prisma/schema.prisma` → `Product`, `Task`, `ClaudeJob` velden uit migration `20260508085909_add_job_model_selection_fields`