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

feat(PBI-67): model + mode-selectie per ClaudeJob-kind (#169)

Browse source 
* feat(PBI-67/ST-1297): datamodel-velden voor job-model-selectie

Voegt 8 nieuwe optionele velden toe verspreid over Product, Task en
ClaudeJob ten dienste van de override-cascade:

  task.requires_opus → job.requested_* → product.preferred_* → kind-default

Bestaande rijen krijgen NULL (Product/ClaudeJob) of false (Task) en
vallen daarmee terug op de kind-defaults uit de resolver (ST-1298).

Migration is additief: alleen ALTER TABLE ADD COLUMN, geen RENAME of
DROP. Bestaande factories en seed-script blijven werken zonder
aanpassing omdat alle nieuwe velden default-waardes hebben.

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

* feat(PBI-67/ST-1299): job-config snapshot bij enqueue + worker-flag-runbook

T-789: Snapshot van resolved JobConfig in ClaudeJob.requested_*
bij elke job-creatie. Helper in lib/job-config-snapshot.ts laadt
product (preferred_*) en task (requires_opus) en draait de resolver
uit lib/job-config.ts (mirror van scrum4me-mcp/src/lib/job-config.ts —
zelfde matrix, sync-comment in bestand). Toegepast op alle 5
enqueue-locaties:

  - actions/user-questions.ts          (PLAN_CHAT)
  - actions/sprint-runs.ts × 3         (SPRINT_IMPLEMENTATION x2,
                                        TASK_IMPLEMENTATION loop)
  - actions/ideas.ts                   (IDEA_GRILL / IDEA_MAKE_PLAN)

Test-mocks uitgebreid met product.findUnique en task.findUnique zodat
de helper bij unit tests veilig terugvalt op kind-defaults (alle 563
tests groen).

T-790: Sectie 'Config doorgeven aan Claude Code' toegevoegd aan
docs/runbooks/worker-idempotency.md met CLI-flag-mapping en de
verwachte aanroep per kind. Forward-link naar
docs/runbooks/job-model-selection.md (volgt in T-794).

Plus: docs/plans/job-model-selection.md (de approved plan-doc).

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

* feat(PBI-67/ST-1300): cost-attribution voor thinking-tokens + admin UI

T-792: token-stats + token-history rekenen actual_thinking_tokens nu
mee in de totale kosten (tegen input-rate, conform Anthropic billing).
COALESCE-veilig zodat oude rijen 0 bijdragen i.p.v. NaN. Nieuwe export
`getTokenStatsByKind` aggregeert tokens en kosten per ClaudeJob.kind
zodat we relatieve uitgaven van IDEA_GRILL/IDEA_MAKE_PLAN/PLAN_CHAT/
TASK_IMPLEMENTATION/SPRINT_IMPLEMENTATION kunnen zien.

T-793: admin/jobs Kosten-tabel toont:
  - Nieuwe kolom 'Thinking' (aantal verbruikte thinking-tokens)
  - Mismatch-marker (rood) als requested_model afwijkt van actuele
    model_id — duidt op een worker die de CLI-flag niet doorgaf.
    Tooltip toont aangevraagd model. Geen Sentry/log-noise.

Page-level cost-berekening volgt dezelfde formule (input_price ×
thinking_tokens). 563 tests groen.

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

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

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Janpeter Visser 2026-05-08 11:20:10 +02:00 • committed by GitHub
parent f233dd815e
commit 8c63ba377d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
18 changed files with 648 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

107
docs/runbooks/job-model-selection.md Normal file
View file

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