janpeter/Scrum4Me
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Scrum4Me/docs/runbooks/job-model-selection.md
Janpeter Visser c2633695d2
fix(KIND_DEFAULTS): permission_mode acceptEdits voor idea-kinds + PLAN_CHAT (#172) 
* fix(KIND_DEFAULTS): permission_mode acceptEdits voor idea-kinds + PLAN_CHAT

Spiegel van scrum4me-mcp PR #40. Symptoom: IDEA_GRILL job IDEA-047 werd
3x geclaimd, Claude liep telkens succesvol (exit 0 na 600-900s) maar
deed nooit update_job_status('done'). Lease verliep, retry_count >= 2 →
status FAILED met "agent did not complete job within 2 attempts".

Root cause: KIND_DEFAULTS.permission_mode='plan' voor idea-kinds en
PLAN_CHAT. In autonome batch-mode wacht plan-mode op een human "go" na
elke planning-fase — geen mens in de loop in deze runner-context.

Fix:
- IDEA_GRILL.permission_mode: plan → acceptEdits
- IDEA_MAKE_PLAN.permission_mode: plan → acceptEdits
- PLAN_CHAT.permission_mode: plan → acceptEdits
- PLAN_CHAT.allowed_tools krijgt mcp__scrum4me__update_job_status (ontbrak)

De allowed_tools-lijsten doen de echte sandboxing (geen Bash, geen Edit
voor IDEA_GRILL/PLAN_CHAT). Plan-mode's "veiligheid" wordt al door
tool-allowlists geleverd; acceptEdits is hier puur om Claude door zijn
eigen update_job_status loop te laten lopen zonder approval-wachttijd.

Plus: docs/runbooks/{job-model-selection,worker-idempotency}.md tabellen
bijgewerkt. last_updated note in job-model-selection.md.

Verify: 587 tests in 78 files passed (incl. nieuwe lib/job-config tests).

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

* chore: remove .claude/scheduled_tasks.lock per ongeluk meegecommit

Lokale tooling-lock-file van de cowork-skills, hoort niet in de repo.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-09 11:33:03 +02:00

141 lines
6.1 KiB
Markdown
Raw Permalink Blame History

---
title: "Job-model-selectie per ClaudeJob-kind"
status: active
audience: [ai-agent, contributor]
language: nl
last_updated: 2026-05-09 (idea-kinds + PLAN_CHAT permission_mode → acceptEdits)
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 | `acceptEdits` | 15 | Read, Grep, Glob, WebSearch, AskUserQuestion |
| `IDEA_MAKE_PLAN` | `claude-opus-4-7` | 24 000 | `acceptEdits` | 20 | Read, Grep, Glob, WebSearch, AskUserQuestion, Write |
| `PLAN_CHAT` | `claude-sonnet-4-6` | 6 000 | `acceptEdits` | 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) |
**Note over `max_turns`** (sinds queue-loop-refactor): dit veld blijft
audit-only. Claude CLI 2.1.x heeft géén `--max-turns` flag — de waarde
wordt gesnapshot in `ClaudeJob.requested_*` voor cost-attribution maar
niet doorgegeven aan Claude. Zie
[worker-idempotency.md](./worker-idempotency.md#config-doorgeven-aan-claude-code-pbi-67).
**Note over `thinking_budget`**: de CLI heeft alleen `--effort
{low,medium,high,xhigh,max}`. De runner mapt het numerieke budget naar
de juiste effort-laag via `mapBudgetToEffort()` in `lib/job-config.ts`.
**Note over `allowed_tools`**: de defaults sluiten bewust
`mcp__scrum4me__wait_for_job`, `check_queue_empty` en
`get_idea_context` uit. De runner claimt voor Claude — vangrail tegen
recursieve claims binnen één invocation.
**`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).
---
## Runner-architectuur (sinds 2026-05-09 queue-loop-refactor)
`scrum4me-docker/bin/run-one-job.ts` draait **één Claude-invocation per
geclaimde job**. De runner leest de `config` uit de
`wait_for_job`-payload (resolved via deze module) en bouwt
kind-specifieke CLI-flags. Voor de exacte flag-mapping (incl. `--effort`
en `--allowedTools`) zie
[worker-idempotency.md](./worker-idempotency.md#config-doorgeven-aan-claude-code-pbi-67).
Praktische gevolgen:
- Per job-spawn een nieuwe Claude-invocation met andere flags — geen
config-mismatch tussen jobs in dezelfde queue-run.
- Verschillen tussen `requested_model` en `model_id` in admin → Jobs
duiden óf op handmatige DB-overrides tussen enqueue en claim, óf op
Claude die zelf een ander model rapporteerde (bv. fallback bij
overload).
- Plan: [queue-loop-extraction.md](../plans/queue-loop-extraction.md).
## 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`
Reference in a new issue View git blame Copy permalink