From 4b7b1429c82c41d727669a3acdcd3ec928a598c9 Mon Sep 17 00:00:00 2001 From: Madhura68 Date: Fri, 8 May 2026 11:18:03 +0200 Subject: [PATCH] docs(PBI-67/ST-1301): runbook + CLAUDE.md updates voor model/mode-selectie MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- CLAUDE.md | 2 + docs/INDEX.md | 1 + docs/plans/job-model-selection.md | 2 +- docs/runbooks/job-model-selection.md | 107 +++++++++++++++++++++++++++ 4 files changed, 111 insertions(+), 1 deletion(-) create mode 100644 docs/runbooks/job-model-selection.md diff --git a/CLAUDE.md b/CLAUDE.md index e368c38..72b4e92 100644 --- 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` | --- diff --git a/docs/INDEX.md b/docs/INDEX.md index 22c421e..54a1e1e 100644 --- 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 | diff --git a/docs/plans/job-model-selection.md b/docs/plans/job-model-selection.md index c497c81..e6786d9 100644 --- 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 --- diff --git a/docs/runbooks/job-model-selection.md b/docs/runbooks/job-model-selection.md new file mode 100644 index 0000000..aa67480 --- /dev/null +++ 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`