Scrum4Me/docs/plans/job-model-selection.md

# Plan: model + mode-selectie per ClaudeJob-kind

## Context

`ClaudeJob` heeft 5 kinds (`TASK_IMPLEMENTATION`, `IDEA_GRILL`, `IDEA_MAKE_PLAN`, `PLAN_CHAT`, `SPRINT_IMPLEMENTATION`) maar er is **geen per-kind model-/mode-configuratie**. Alle jobs draaien op de Claude Code CLI default. `ClaudeJob.model_id` ([prisma/schema.prisma](../../prisma/schema.prisma)) wordt alleen post-hoc gevuld voor kostenberekening via [lib/insights/token-stats.ts](../../lib/insights/token-stats.ts) en `model_prices` (PBI-66).

Probleem: een grill-sessie verdient meer thinking-budget en geen file-edits, terwijl een task-implementation acceptEdits/bypassPermissions in een worktree wil. Nu is dat allemaal hetzelfde — wat leidt tot:

- Te dure runs (Opus voor triviale Haiku-waardige taken)
- Te schrale runs (Sonnet zonder thinking voor architectuurkeuze in `IDEA_MAKE_PLAN`)
- Geen cost-attribution per kind voor budgettering
- Geen product-level override voor klanten met eigen model-voorkeur

**Doel:** een resolver die per `ClaudeJob` bepaalt: model, thinking-budget, permission-mode, max_turns, allowed_tools — gebaseerd op kind-defaults met overrides per product en per job. De worker geeft de geresolveerde config door aan Claude Code via CLI-flags.

**Niet-doel:** de runtime vervangen door de Claude Agent SDK. Worker blijft Claude Code CLI; we bouwen erbovenop.

## Aanpak

### 1. Datamodel-uitbreiding

| Tabel | Veld | Type | Doel |
|---|---|---|---|
| `Product` | `preferred_model` | `String?` | Product-brede default (bv. "alle taken op Sonnet voor budget") |
| `Product` | `thinking_budget_default` | `Int?` | Idem voor thinking |
| `Task` | `requires_opus` | `Boolean @default(false)` | Per-task escalatie (cross-file refactor) |
| `ClaudeJob` | `requested_model` | `String?` | Snapshot van resolved model (audit) |
| `ClaudeJob` | `requested_thinking_budget` | `Int?` | Snapshot van resolved budget |
| `ClaudeJob` | `requested_permission_mode` | `String?` | Snapshot van resolved mode |
| `ClaudeJob` | `actual_thinking_tokens` | `Int?` | Werkelijk verbruikte thinking-tokens (cost-attribution) |

Migration is additief. Bestaande rijen krijgen `NULL` → resolver valt terug op kind-defaults.

### 2. Centrale resolver

**Locatie:** `scrum4me-mcp/src/lib/job-config.ts` (nieuw bestand in MCP-repo).

```ts
type JobConfig = {
  model: 'claude-opus-4-7' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001'
  thinking_budget: number  // 0 = uit
  permission_mode: 'plan' | 'default' | 'acceptEdits' | 'bypassPermissions'
  max_turns: number | null  // null = onbegrensd
  allowed_tools: string[] | null  // null = alle
}

function resolveJobConfig(job: ClaudeJob, product: Product, task?: Task): JobConfig
```

**Resolutie-volgorde** (eerste match wint):
1. `task.requires_opus === true` → forceer model = `claude-opus-4-7`
2. `job.requested_*` (al ingevuld door enqueue-laag)
3. `product.preferred_*`
4. **Kind-default** uit deze tabel:

| Kind | Model | Thinking | Permission | max_turns | allowed_tools |
|---|---|---|---|---|---|
| `IDEA_GRILL` | sonnet-4-6 | 12000 | `plan` | 15 | Read, Grep, Glob, WebSearch, AskUserQuestion |
| `IDEA_MAKE_PLAN` | opus-4-7 | 24000 | `plan` | 20 | Read, Grep, Glob, WebSearch, AskUserQuestion, Write |
| `PLAN_CHAT` | sonnet-4-6 | 6000 | `plan` | 5 | Read, Grep, AskUserQuestion |
| `TASK_IMPLEMENTATION` | sonnet-4-6 | 6000 | `bypassPermissions` | 50 | null |
| `SPRINT_IMPLEMENTATION` | sonnet-4-6 | 6000 | `bypassPermissions` | null | null |

`bypassPermissions` is verdedigbaar omdat task/sprint-implementatie altijd in een geïsoleerde git-worktree draait (zie [docs/runbooks/branch-and-commit.md](../runbooks/branch-and-commit.md)). Voor productie-omgevingen kan `Product.preferred_permission_mode = 'acceptEdits'` als opt-in.

### 3. `wait_for_job` response uitbreiden

Huidig: `wait_for_job` returnt `{ job_id, kind, context }`. Toevoegen: `config: JobConfig`.

Worker leest `config` en spawnt Claude Code subprocess met:
```
claude --model {config.model} \
       --permission-mode {config.permission_mode} \
       --thinking-budget {config.thinking_budget} \
       [--max-turns {config.max_turns}] \
       [--allowed-tools "{config.allowed_tools.join(',')}"]
```

Documentatie van vlaggen verwijst naar [Claude Code model-config](https://code.claude.com/docs/en/model-config). Als een vlag (nog) niet bestaat in de huidige CLI: skippen + log-warning, niet hardcrashen.

### 4. Audit + cost-attribution

Bij job-completion (in `update_job_status` MCP-tool):
- `actual_thinking_tokens` schrijven naar `ClaudeJob` (al beschikbaar in Claude Code result-payload)
- Bestaande `model_id`-update behouden (cost-berekening via `model_prices`)

Token-stats-laag ([lib/insights/token-stats.ts](../../lib/insights/token-stats.ts)) uitbreiden:
- Aggregeren per kind (nu per dag/product) — feature-gate tot ST-N nodig
- Thinking-tokens apart tonen (andere prijs dan output-tokens)

### 5. Documentatie

- **Nieuw:** [docs/runbooks/job-model-selection.md](../runbooks/job-model-selection.md) — de matrix + wanneer je override gebruikt
- **CLAUDE.md** Hardstop-bullet: "Model/mode per ClaudeJob: kind-default → product → task — zie runbook"
- **Patterns quickref** in CLAUDE.md: regel toevoegen voor `job-config.ts` resolver-pattern

## Voorgestelde PBI/story-breakdown

Voor de Scrum4Me-MCP `create_pbi` / `create_story` / `create_task` ronde na goedkeuring:

**PBI:** "Model + mode-selectie per ClaudeJob-kind"

| Story | Doel | Tasks (indicatief) |
|---|---|---|
| **ST-1: Datamodel + migration** | Velden op Product/Task/ClaudeJob | Schema wijzigen · migration · Prisma generate · seed/factories updaten |
| **ST-2: Resolver in scrum4me-mcp** | `job-config.ts` met kind-defaults + override-cascade | Resolver-functie · unit tests per kind · export voor MCP-tools |
| **ST-3: `wait_for_job` integratie** | Config in response + snapshot in `requested_*` | Tool-output uitbreiden · enqueue-laag snapshot · worker-flag-passing documenteren |
| **ST-4: Audit + cost-attribution** | `actual_thinking_tokens` opslaan + tonen | `update_job_status` uitbreiden · token-stats per kind · admin/jobs UI-kolom |
| **ST-5: Documentatie** | Runbook + CLAUDE.md updates | runbook schrijven · CLAUDE.md hardstop · patterns-row |

ST-1 → ST-2 → ST-3 zijn de kritieke pad-stories. ST-4 en ST-5 kunnen parallel met ST-3.

## Bestanden

| Bestand | Repo | Actie |
|---|---|---|
| `prisma/schema.prisma` | scrum4me | **Wijzigen** — 7 nieuwe velden |
| `prisma/migrations/<ts>_job_model_selection/` | scrum4me | **Nieuw** — additive migration |
| `scrum4me-mcp/src/lib/job-config.ts` | scrum4me-mcp | **Nieuw** — resolver |
| `scrum4me-mcp/src/lib/job-config.test.ts` | scrum4me-mcp | **Nieuw** — unit tests per kind |
| `scrum4me-mcp/src/tools/wait-for-job.ts` | scrum4me-mcp | **Wijzigen** — config in response |
| `scrum4me-mcp/src/tools/update-job-status.ts` | scrum4me-mcp | **Wijzigen** — `actual_thinking_tokens` |
| `lib/insights/token-stats.ts` | scrum4me | **Wijzigen** — per-kind aggregatie + thinking-prijs |
| `actions/admin/jobs.ts` + UI-kolom | scrum4me | **Wijzigen** — model/mode tonen |
| `docs/runbooks/job-model-selection.md` | scrum4me | **Nieuw** — runbook |
| `CLAUDE.md` | scrum4me | **Wijzigen** — hardstop-bullet + patterns-row |

## Verificatie

Per story:
- **ST-1:** `npm run verify` slaagt na schema-wijziging; migration runt clean op test-DB
- **ST-2:** unit tests dekken alle 5 kinds × 4 cascade-niveaus (default/product/job/task)
- **ST-3:** integratietest: enqueue een `IDEA_GRILL` met product-override → `wait_for_job` returnt config met override toegepast
- **ST-4:** end-to-end: run een dummy-job, verifieer dat `actual_thinking_tokens` ingevuld wordt en dat token-stats het kostbedrag correct rekent (input + output + thinking-input rate)
- **ST-5:** `npm run docs:check-links` groen; CLAUDE.md ≤ 150 regels

End-to-end-validatie van het geheel:
1. Maak een nieuw idee → `IDEA_GRILL`-job → controleer dat de worker met `--permission-mode plan` en `--thinking-budget 12000` start
2. Approve het idee → `IDEA_MAKE_PLAN`-job → controleer Opus-aanroep met thinking 24000
3. Sprint starten → `SPRINT_IMPLEMENTATION` met `bypassPermissions` in worktree
4. Admin-jobs-pagina toont per job het gebruikte model + thinking-tokens

## Vastgelegde beslissingen (review-uitkomst)

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`) 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

---

Bij goedkeuring: PBI + 5 stories + ~20 tasks aanmaken via `mcp__scrum4me__create_pbi/story/task`. Volgorde: ST-1 → ST-2 → ST-3 → (ST-4 ‖ ST-5).