feat(usage): record_usage_segment, schatting in create_task, get_estimate_history (IDEA-235 T8) #192

Merged
janpeter merged 2 commits from feat/idea-235-t8-usage-tools into main 2026-10-05 14:14:44 +02:00
Owner

IDEA-235 plan Taak 8 (T-2007): MCP-tools voor sessie-usage en schattingen. Spec §4.5, §5, §9.

Merge-volgorde: eerst janpeter/scrum4me-shared#71 (de submodule wijst naar 9f1958d op die branch), daarna janpeter/Scrum4Me#307, daarna deze.

record_usage_segment (nieuw)

  • Eerst eigendom en toegang (RR4-6), dan de levenscyclus. Een nieuw segment legt eigenaar, product en sprint vast uit anchor_task_id. Een kop op een bestaand segment doet niets. Een sluitbericht sluit één keer (updateMany … where ended_at IS NULL, regels in dezelfde transactie). Elk bericht op een gesloten segment slaagt zonder effect.
  • task_id: null = overhead; bij een taaksegment moet het anker gelijk zijn aan task_id. Een sluitbericht dat als eerste aankomt maakt het segment alsnog aan.
  • ended_reason in API-spelling → DB via taskStatusFromApi plus SWITCHED, SESSION_END en UNTRACKED. reported_cost_usd = cost_end_usd − cost_start_usd (null als er een ontbreekt).
  • Blijvende fouten beginnen met USAGE_SEGMENT_REJECTED (taak onbekend of ontoegankelijk, geen sprint, ander eigenaar, ongeldige invoer). Al het andere is tijdelijk. Dit is het contract voor de outbox in T9.

create_task

  • Optionele schatting estimate_active_minutes, estimate_usd, estimate_basis: alle drie of geen (ESTIMATE_INCOMPLETE). Eén task_estimates-rij in de transactie van de taak.
  • Een brontest borgt dat geen andere code task_estimates schrijft.
  • PPE: de schatting hoort bij het gehashte verzoek, maar alleen als die is meegegeven. Hashes van aanroepen zonder schatting blijven gelijk.

get_estimate_history (nieuw, lezen)

  • De laatste meetbare taken (predicaat uit scrum4me-shared): geschat en werkelijk (minuten, USD), ratio's en de basis.
  • USD alleen als elke regel een prijs heeft; anders usd: null, usd_status: "no_price" en alleen een tijdratio.

Tests

  • Unit: validatie, levenscyclus, eigenaarscontrole vóór de levenscyclus, race-verlies bij het sluiten, mapping van redenen, schatting (6 deelcombinaties).
  • Integratie (__tests__/usage-ledger.integration.test.ts, TEST_DATABASE_URL, skipt zonder): lokaal gedraaid tegen een wegwerp-Postgres 17 met de volledige migratieketen inclusief usage_ledger, 10/10 groen. Dekt:
    • acceptatie 1–5;
    • een taak die naar een andere sprint gaat;
    • twee gelijktijdige sluitingen;
    • get_estimate_history op de fixture uit scrum4me-shared: alleen measurable en unpriced-line; USD 0.2320, kostenratio alleen voor measurable.
  • Mutatiecontrole: zonder de ended_at IS NULL-guard of zonder de eigenaarscontrole faalt telkens een unit- én een integratietest.
  • npm run build, npm test (2128 passed) groen; canary:stdio ok, 88 tools.

Geen productiedeploy zonder JP.

🤖 Generated with Claude Code

IDEA-235 plan Taak 8 (T-2007): MCP-tools voor sessie-usage en schattingen. Spec §4.5, §5, §9. **Merge-volgorde:** eerst janpeter/scrum4me-shared#71 (de submodule wijst naar `9f1958d` op die branch), daarna janpeter/Scrum4Me#307, daarna deze. ### `record_usage_segment` (nieuw) - Eerst eigendom en toegang (RR4-6), dan de levenscyclus. Een nieuw segment legt eigenaar, product en sprint vast uit `anchor_task_id`. Een kop op een bestaand segment doet niets. Een sluitbericht sluit één keer (`updateMany … where ended_at IS NULL`, regels in dezelfde transactie). Elk bericht op een gesloten segment slaagt zonder effect. - `task_id: null` = overhead; bij een taaksegment moet het anker gelijk zijn aan `task_id`. Een sluitbericht dat als eerste aankomt maakt het segment alsnog aan. - `ended_reason` in API-spelling → DB via `taskStatusFromApi` plus `SWITCHED`, `SESSION_END` en `UNTRACKED`. `reported_cost_usd` = `cost_end_usd − cost_start_usd` (null als er een ontbreekt). - Blijvende fouten beginnen met `USAGE_SEGMENT_REJECTED` (taak onbekend of ontoegankelijk, geen sprint, ander eigenaar, ongeldige invoer). Al het andere is tijdelijk. Dit is het contract voor de outbox in T9. ### `create_task` - Optionele schatting `estimate_active_minutes`, `estimate_usd`, `estimate_basis`: alle drie of geen (`ESTIMATE_INCOMPLETE`). Eén `task_estimates`-rij in de transactie van de taak. - Een brontest borgt dat geen andere code `task_estimates` schrijft. - **PPE:** de schatting hoort bij het gehashte verzoek, maar alleen als die is meegegeven. Hashes van aanroepen zonder schatting blijven gelijk. ### `get_estimate_history` (nieuw, lezen) - De laatste meetbare taken (predicaat uit scrum4me-shared): geschat en werkelijk (minuten, USD), ratio's en de basis. - USD alleen als elke regel een prijs heeft; anders `usd: null`, `usd_status: "no_price"` en alleen een tijdratio. ### Tests - Unit: validatie, levenscyclus, eigenaarscontrole vóór de levenscyclus, race-verlies bij het sluiten, mapping van redenen, schatting (6 deelcombinaties). - **Integratie** (`__tests__/usage-ledger.integration.test.ts`, `TEST_DATABASE_URL`, skipt zonder): lokaal gedraaid tegen een wegwerp-Postgres 17 met de volledige migratieketen inclusief `usage_ledger`, 10/10 groen. Dekt: - acceptatie 1–5; - een taak die naar een andere sprint gaat; - twee gelijktijdige sluitingen; - `get_estimate_history` op de fixture uit scrum4me-shared: alleen `measurable` en `unpriced-line`; USD `0.2320`, kostenratio alleen voor `measurable`. - Mutatiecontrole: zonder de `ended_at IS NULL`-guard of zonder de eigenaarscontrole faalt telkens een unit- én een integratietest. - `npm run build`, `npm test` (2128 passed) groen; `canary:stdio` ok, 88 tools. Geen productiedeploy zonder JP. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(usage): record_usage_segment, schatting in create_task, get_estimate_history (IDEA-235 T8)
Some checks failed
CI / Final merge attestation and immutable publication (pull_request) Has been skipped
CI / PR candidate (never published) (pull_request) Failing after 8m36s
e5fc23ee91
- record_usage_segment: segmenten van de usage-ledger-mod. Eigendom en
  toegang eerst (RR4-6), dan de levenscyclus van spec §4.5: nieuw
  segment legt eigenaar/product/sprint vast uit het anker; kop op een
  bestaand segment en elk bericht op een gesloten segment doen niets;
  een sluitbericht sluit één keer (updateMany op ended_at IS NULL,
  regels in dezelfde transactie). ended_reason in API-spelling via
  taskStatusFromApi. reported_cost_usd = eind − begin. Blijvende fouten
  dragen het prefix USAGE_SEGMENT_REJECTED.
- create_task: optionele schatting, alle drie velden of geen, één
  task_estimates-rij in de transactie van de taak; een test borgt dat
  er geen tweede schrijfweg is. Met PPE hoort de schatting bij het
  gehashte verzoek, alleen als die er is.
- get_estimate_history: laatste meetbare taken via de gedeelde SQL uit
  scrum4me-shared (submodule-bump), USD alleen bij volledige prijzen.

Integratietest tegen echte Postgres (TEST_DATABASE_URL) met de
fixture uit scrum4me-shared.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
s4m-codex-reviewer requested changes 2026-10-05 13:28:53 +02:00
Dismissed
s4m-codex-reviewer left a comment

REQUEST_CHANGES

Findings:

  • error (blokkerend) — src/tools/record-usage-segment.ts:194 — De MCP-SDK valideert de strikte inputSchema vóór de handler. Een bericht met bijvoorbeeld active_ms: -1 geeft MCP error -32602: Input validation error..., zonder USAGE_SEGMENT_REJECTED. Bevestigd met de PR-schema en een in-memory MCP-client: de handler wordt niet aangeroepen. Volgens het gedocumenteerde outbox-contract wordt deze blijvend ongeldige invoer daardoor als tijdelijk behandeld en opnieuw geprobeerd. Classificeer ook schemafouten als permanent en voeg een test via tools/call toe.
  • warning — tests/record-usage-segment.test.ts:110 — De nieuwe unique-retry gebruikt alleen een handgemaakt P2002-object als regressietest. De integratiesuite dekt gelijktijdige sluitingen, maar geen create-race/werkelijke 23505. Het productpatroon prisma-driver-adapter-error-matching schrijft hiervoor een echte PostgreSQL-test voor.

Plan gekoppeld via pr_refs (product Scrum4Me), referentie: T-2007 (Scrum4Me), story ST-1630. Geen omitted onderdelen. De diff past bij de T8-scope: eigenaarscontrole, transactionele eerste sluiting, optionele bevroren schatting en gedeelde SQL voor historie. De overige storyonderdelen vallen buiten deze PR. Het permanente-foutcontract dat de PR zegt af te ronden is door de blokkerende finding nog niet volledig gerealiseerd.

Verificatie op head e5fc23ee91adf45208b48a7635d02ff24d4ce6b8: PR resolveert en head komt overeen; Prisma-generatie, schema-driftcheck en beide TypeScript-checks geslaagd. MCP-reproductie van de finding geslaagd. Vitest kon lokaal niet starten doordat /tmp noexec is (native binding/esbuild); geen lokale groene testsuite geclaimd. Geen wegwerp-Postgres beschikbaar. De PR vermeldt eigen groene tests; CI stond bij controle nog pending. Documentatie en registratie van de tools zijn aanwezig.

# REQUEST_CHANGES Findings: - **error (blokkerend)** — src/tools/record-usage-segment.ts:194 — De MCP-SDK valideert de strikte `inputSchema` vóór de handler. Een bericht met bijvoorbeeld `active_ms: -1` geeft `MCP error -32602: Input validation error...`, zonder `USAGE_SEGMENT_REJECTED`. Bevestigd met de PR-schema en een in-memory MCP-client: de handler wordt niet aangeroepen. Volgens het gedocumenteerde outbox-contract wordt deze blijvend ongeldige invoer daardoor als tijdelijk behandeld en opnieuw geprobeerd. Classificeer ook schemafouten als permanent en voeg een test via `tools/call` toe. - **warning** — __tests__/record-usage-segment.test.ts:110 — De nieuwe unique-retry gebruikt alleen een handgemaakt P2002-object als regressietest. De integratiesuite dekt gelijktijdige sluitingen, maar geen create-race/werkelijke 23505. Het productpatroon `prisma-driver-adapter-error-matching` schrijft hiervoor een echte PostgreSQL-test voor. Plan gekoppeld via pr_refs (product Scrum4Me), referentie: T-2007 (Scrum4Me), story ST-1630. Geen omitted onderdelen. De diff past bij de T8-scope: eigenaarscontrole, transactionele eerste sluiting, optionele bevroren schatting en gedeelde SQL voor historie. De overige storyonderdelen vallen buiten deze PR. Het permanente-foutcontract dat de PR zegt af te ronden is door de blokkerende finding nog niet volledig gerealiseerd. Verificatie op head `e5fc23ee91adf45208b48a7635d02ff24d4ce6b8`: PR resolveert en head komt overeen; Prisma-generatie, schema-driftcheck en beide TypeScript-checks geslaagd. MCP-reproductie van de finding geslaagd. Vitest kon lokaal niet starten doordat /tmp noexec is (native binding/esbuild); geen lokale groene testsuite geclaimd. Geen wegwerp-Postgres beschikbaar. De PR vermeldt eigen groene tests; CI stond bij controle nog pending. Documentatie en registratie van de tools zijn aanwezig.
test(usage): parity-check volgt de shared-pin 9f1958d (IDEA-235 T8)
All checks were successful
CI / Final merge attestation and immutable publication (pull_request) Has been skipped
CI / PR candidate (never published) (pull_request) Successful in 8m15s
e6440a60d3
De submodule wijst naar scrum4me-shared#71 (9f1958dd); CURRENT_SHARED_COMMIT
stond nog op de vorige pin b3d2b98, waardoor ppe-bundle1-parity faalde.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
s4m-codex-reviewer left a comment

REQUEST_CHANGES

Plan gekoppeld via pr_refs (product Scrum4Me), referentie: T-2007 (Scrum4Me), story ST-1630. Geen omitted onderdelen. Beoordeeld binnen de scope van IDEA-235 T8; de overige storyonderdelen worden door deze PR niet als afgerond geclaimd.

Findings:

  • error — src/tools/record-usage-segment.ts:194: De SDK valideert inputSchema vóór handleRecordUsageSegment. Een ongeldige UUID geeft MCP error -32602: Input validation error, zonder USAGE_SEGMENT_REJECTED. Het gedocumenteerde outboxcontract classificeert elke andere fout als tijdelijk, waardoor ongeldige berichten eindeloos blijven worden aangeboden. Normaliseer ook schemafouten naar het permanente foutcontract (of stem een expliciete InvalidParams-classificatie met de client af) en test via de geregistreerde MCP-tool.
  • error — src/tools/record-usage-segment.ts:122: validate vergelijkt ended_at uitsluitend met started_at uit het nieuwe bericht, terwijl een bestaand segment zijn oorspronkelijke started_at behoudt. Reproductie met opgeslagen start 10:00, meegestuurde start 08:00 en einde 09:00 sluit succesvol met einde vóór de opgeslagen start. Dit schendt spec §6 (altijd ended_at ≥ started_at). Lees het opgeslagen starttijdstip en valideer een eerste sluiting daartegen vóór updateMany; voeg een regressietest toe.

De transactie bij sluiting, eigenaarscontrole, schatting bij taakcreatie en gedeelde usage-SQL volgen verder de bedoelde patronen. Documentatie en tests zijn toegevoegd, maar de tests missen bovenstaande grensgevallen.

Verificatie op head e6440a60d3: src- en test-typecheck geslaagd; beide findings afzonderlijk gereproduceerd met de geïnstalleerde SDK respectievelijk de getranspileerde handler met DB-stubs. Vitest kon in deze omgeving niet starten wegens native-modulebeperkingen op /tmp. De Postgres-integratiesuite is hier niet uitgevoerd.

# REQUEST_CHANGES Plan gekoppeld via pr_refs (product Scrum4Me), referentie: T-2007 (Scrum4Me), story ST-1630. Geen omitted onderdelen. Beoordeeld binnen de scope van IDEA-235 T8; de overige storyonderdelen worden door deze PR niet als afgerond geclaimd. Findings: - **error — src/tools/record-usage-segment.ts:194:** De SDK valideert inputSchema vóór handleRecordUsageSegment. Een ongeldige UUID geeft MCP error -32602: Input validation error, zonder USAGE_SEGMENT_REJECTED. Het gedocumenteerde outboxcontract classificeert elke andere fout als tijdelijk, waardoor ongeldige berichten eindeloos blijven worden aangeboden. Normaliseer ook schemafouten naar het permanente foutcontract (of stem een expliciete InvalidParams-classificatie met de client af) en test via de geregistreerde MCP-tool. - **error — src/tools/record-usage-segment.ts:122:** validate vergelijkt ended_at uitsluitend met started_at uit het nieuwe bericht, terwijl een bestaand segment zijn oorspronkelijke started_at behoudt. Reproductie met opgeslagen start 10:00, meegestuurde start 08:00 en einde 09:00 sluit succesvol met einde vóór de opgeslagen start. Dit schendt spec §6 (altijd ended_at ≥ started_at). Lees het opgeslagen starttijdstip en valideer een eerste sluiting daartegen vóór updateMany; voeg een regressietest toe. De transactie bij sluiting, eigenaarscontrole, schatting bij taakcreatie en gedeelde usage-SQL volgen verder de bedoelde patronen. Documentatie en tests zijn toegevoegd, maar de tests missen bovenstaande grensgevallen. Verificatie op head e6440a60d35ae7fba7cb1cff71833b4b7f7c5506: src- en test-typecheck geslaagd; beide findings afzonderlijk gereproduceerd met de geïnstalleerde SDK respectievelijk de getranspileerde handler met DB-stubs. Vitest kon in deze omgeving niet starten wegens native-modulebeperkingen op /tmp. De Postgres-integratiesuite is hier niet uitgevoerd.
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
janpeter/scrum4me-mcp!192
No description provided.