feat(deploy-advice): adviseur, DeployAdvice-model en advise/run-routes (ST-080, IDEA-275) #293

Merged
janpeter merged 3 commits from claude/st080-deploy-advice-backend-b2b8db into main 2026-10-22 06:32:53 +02:00
Owner

IDEA-275 increment 2, story ST-080 (sprint S-2026-10-21-2, PBI-26). Dashboardkant van "Plan + advies → Deploy" voor deploy_scrum4me: adviseur, opslag en de twee API-routes. Onafhankelijk van ST-079 (ops-agent): de tests mocken de agent; de routes roepen de command-keys scrum4me_deploy_advice_input en s4m_queue_notify_jp aan die ST-079 toevoegt. ST-081 (pagina + auditblok) bouwt op de responsvormen hieronder.

T-214 — execAgentResult, adviseur en DeployAdvice-model (99c2326e0)

  • lib/agent-client.ts: execAgentResult(commandKey, args, { stdin?, timeoutMs? }) → { code, stdout, stderr }. Parseert de SSE van /agent/v1/exec per event zoals ops-agent/src/routes/exec.ts die uitzendt (stdout/stderr met { data }, exit met { code }, error → throw); stdin alleen in de body als meegegeven; AbortSignal.timeout(timeoutMs ?? 60_000). execAgent ongewijzigd.
  • lib/deploy-advice/types.ts: FLAG_NAMES = ['web','worker_fleet','codex','workers'] (bewust zonder mcp_pin), AdviceInput, DeployAdviceOutput, AdviceResult, limieten 12 warnings / 400 / 600 tekens.
  • lib/deploy-advice/advisor.ts (server-only): claude-haiku-5-5, max_tokens 4000, timeout 60 s, strict tool deploy_advice (additionalProperties: false), tool_choice: auto met "precies één keer aanroepen", systeemprompt met de planner-regels van increment 1 en de signaalset uit spec rev 2. redactSecrets(...).text op commit-subjects vóór verzending en op summary/warnings erna; eigen vormcontrole; al-true vlaggen weggefilterd; mcp_pin/onbekende vlaggen → ongeldig. Refusal, max_tokens, geen tool-call, APIError (incl. RateLimitError) en ontbrekende sleutel → { advice: null, error_text }, nooit een throw. cost_usd uit usage ($0,10/$0,50 per 1M).
  • Prisma: model DeployAdvice (uniek per dry-run, cascade op FlowRun, applied_flow_run_id nullable, index daarop voor de auditpagina) + tegenrelatie deploy_advice_dry_run op FlowRun.
  • Migratie prisma/migrations/20261022120000_deploy_advice/migration.sql: handgeschreven, SQL byte-gelijk aan prisma migrate diff --from-empty --to-schema; draait mee in update_ops_dashboard.
  • Tests (base): test/agent-client-exec-result.test.ts, test/deploy-advice-advisor.test.ts.

T-215 — advise-route en run-route (4cac05c8e)

  • POST /api/flows/deploy-scrum4me/advise { dry_run_flow_run_id }: 401/403; 404 bij onbekende dry-run of andere gebruiker/host; 400 bij andere flow, geen dry-run, niet-success of ouder dan 30 min; 502 als het input-command code ≠ 0 geeft (stderr in error) of geen JSON levert; 409 als plan.generated_at buiten [started_at, ended_at ?? now] valt of als het bestaande advies al toegepast is; adviseDeploy + upsert; bij een block-warning s4m_queue_notify_jp met key deploy-scrum4me-advice:<advice_id> en buildBlockNotice(...) op stdin, fail-open (notify_error).
    Respons 200: { advice_id, plan, input, advice, error_text, notify_error }.
  • lib/deploy-advice/notify.ts: buildBlockNotice(advice, host, dashboardUrl, { advice_id, dry_run_flow_run_id, plan_generated_at }).
  • POST /api/flows/run: optioneel plan_overrides: { add_flags } en advice_id, uitsluitend bij deploy_scrum4me (400); add_flags unieke vlaggen ⊆ FLAG_NAMES (400); advies van deze gebruiker (via de dry-run) en host, < 30 min, nog niet toegepast (404/409). Alle validatie vóór flowRun.create; daarna applied_flow_run_id zetten en plan_overrides in de agent-body. Zonder overrides is de agent-body ongewijzigd.
  • Tests (base): test/deploy-advice-advise-route.test.ts, test/flows-run-route-overrides.test.ts.

Verificatie (lokaal)

  • npx vitest run op de vier nieuwe suites + ci-test-groups, flow-reconcile, agent-fetch-401: 7 bestanden, 66 tests groen.
  • npm run typecheck (build-info + tsc --noEmit) groen na fresh-worktree-setup; npx prisma validate groen.

Afwijkingen van het plan

  • buildBlockNotice kreeg een vierde argument (advice_id, dry-run-id, plan-tijdstip) zodat de melding naar mac:jp de bron noemt; dashboardUrl is de request-origin, geen nieuwe env-var.
  • Index op DeployAdvice.applied_flow_run_id toegevoegd (lookup van het auditblok in ST-081).
  • isAdviceConfigured() zit in de adviseur zelf (geen sleutel → error_text, geen Claude-call), zodat ook de route fail-open blijft.

🤖 Generated with Claude Code

IDEA-275 increment 2, story ST-080 (sprint S-2026-10-21-2, PBI-26). Dashboardkant van "Plan + advies → Deploy" voor `deploy_scrum4me`: adviseur, opslag en de twee API-routes. Onafhankelijk van ST-079 (ops-agent): de tests mocken de agent; de routes roepen de command-keys `scrum4me_deploy_advice_input` en `s4m_queue_notify_jp` aan die ST-079 toevoegt. ST-081 (pagina + auditblok) bouwt op de responsvormen hieronder. ## T-214 — execAgentResult, adviseur en DeployAdvice-model (99c2326e0) - `lib/agent-client.ts`: `execAgentResult(commandKey, args, { stdin?, timeoutMs? })` → `{ code, stdout, stderr }`. Parseert de SSE van `/agent/v1/exec` per event zoals `ops-agent/src/routes/exec.ts` die uitzendt (`stdout`/`stderr` met `{ data }`, `exit` met `{ code }`, `error` → throw); `stdin` alleen in de body als meegegeven; `AbortSignal.timeout(timeoutMs ?? 60_000)`. `execAgent` ongewijzigd. - `lib/deploy-advice/types.ts`: `FLAG_NAMES = ['web','worker_fleet','codex','workers']` (bewust zonder `mcp_pin`), `AdviceInput`, `DeployAdviceOutput`, `AdviceResult`, limieten 12 warnings / 400 / 600 tekens. - `lib/deploy-advice/advisor.ts` (server-only): `claude-haiku-5-5`, `max_tokens` 4000, timeout 60 s, strict tool `deploy_advice` (`additionalProperties: false`), `tool_choice: auto` met "precies één keer aanroepen", systeemprompt met de planner-regels van increment 1 en de signaalset uit spec rev 2. `redactSecrets(...).text` op commit-subjects vóór verzending en op summary/warnings erna; eigen vormcontrole; al-true vlaggen weggefilterd; `mcp_pin`/onbekende vlaggen → ongeldig. Refusal, `max_tokens`, geen tool-call, `APIError` (incl. `RateLimitError`) en ontbrekende sleutel → `{ advice: null, error_text }`, nooit een throw. `cost_usd` uit `usage` ($0,10/$0,50 per 1M). - Prisma: model `DeployAdvice` (uniek per dry-run, cascade op FlowRun, `applied_flow_run_id` nullable, index daarop voor de auditpagina) + tegenrelatie `deploy_advice_dry_run` op `FlowRun`. - Migratie `prisma/migrations/20261022120000_deploy_advice/migration.sql`: handgeschreven, SQL byte-gelijk aan `prisma migrate diff --from-empty --to-schema`; draait mee in `update_ops_dashboard`. - Tests (base): `test/agent-client-exec-result.test.ts`, `test/deploy-advice-advisor.test.ts`. ## T-215 — advise-route en run-route (4cac05c8e) - `POST /api/flows/deploy-scrum4me/advise` `{ dry_run_flow_run_id }`: 401/403; 404 bij onbekende dry-run of andere gebruiker/host; 400 bij andere flow, geen dry-run, niet-success of ouder dan 30 min; 502 als het input-command code ≠ 0 geeft (stderr in `error`) of geen JSON levert; 409 als `plan.generated_at` buiten `[started_at, ended_at ?? now]` valt of als het bestaande advies al toegepast is; `adviseDeploy` + upsert; bij een `block`-warning `s4m_queue_notify_jp` met key `deploy-scrum4me-advice:<advice_id>` en `buildBlockNotice(...)` op stdin, fail-open (`notify_error`). Respons 200: `{ advice_id, plan, input, advice, error_text, notify_error }`. - `lib/deploy-advice/notify.ts`: `buildBlockNotice(advice, host, dashboardUrl, { advice_id, dry_run_flow_run_id, plan_generated_at })`. - `POST /api/flows/run`: optioneel `plan_overrides: { add_flags }` en `advice_id`, uitsluitend bij `deploy_scrum4me` (400); `add_flags` unieke vlaggen ⊆ `FLAG_NAMES` (400); advies van deze gebruiker (via de dry-run) en host, < 30 min, nog niet toegepast (404/409). Alle validatie vóór `flowRun.create`; daarna `applied_flow_run_id` zetten en `plan_overrides` in de agent-body. Zonder overrides is de agent-body ongewijzigd. - Tests (base): `test/deploy-advice-advise-route.test.ts`, `test/flows-run-route-overrides.test.ts`. ## Verificatie (lokaal) - `npx vitest run` op de vier nieuwe suites + `ci-test-groups`, `flow-reconcile`, `agent-fetch-401`: 7 bestanden, 66 tests groen. - `npm run typecheck` (build-info + `tsc --noEmit`) groen na fresh-worktree-setup; `npx prisma validate` groen. ## Afwijkingen van het plan - `buildBlockNotice` kreeg een vierde argument (advice_id, dry-run-id, plan-tijdstip) zodat de melding naar `mac:jp` de bron noemt; `dashboardUrl` is de request-origin, geen nieuwe env-var. - Index op `DeployAdvice.applied_flow_run_id` toegevoegd (lookup van het auditblok in ST-081). - `isAdviceConfigured()` zit in de adviseur zelf (geen sleutel → `error_text`, geen Claude-call), zodat ook de route fail-open blijft. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
- lib/agent-client.ts: execAgentResult(commandKey, args, { stdin, timeoutMs })
  parseert de SSE van /agent/v1/exec per event (stdout/stderr/exit { code }),
  stuurt stdin alleen mee als gegeven, abort na 60 s; execAgent ongewijzigd.
- lib/deploy-advice/types.ts: FLAG_NAMES (web, worker_fleet, codex, workers;
  bewust zonder mcp_pin), AdviceInput, DeployAdviceOutput, AdviceResult.
- lib/deploy-advice/advisor.ts: claude-haiku-5-5, strict tool deploy_advice,
  tool_choice auto, redactie van commit-subjects vóór en summary/warnings ná
  de call, eigen vormcontrole, al-true vlaggen weggefilterd, kosten uit usage;
  elke fout (geen sleutel, refusal, geen tool-call, APIError) → advice null.
- Prisma: model DeployAdvice (uniek per dry-run, cascade) + migratie
  20261022120000_deploy_advice (gelijk aan prisma migrate diff).
- Tests (base): agent-client-exec-result, deploy-advice-advisor.

IDEA-275 increment 2, spec/plan rev 2.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
feat(deploy-advice): advise-route en plan_overrides/advice_id in de run-route (T-215, ST-080)
All checks were successful
CI / Select checks (pull_request) Successful in 22s
CI / Ops-agent checks (pull_request) Successful in 41s
CI / Deploy artifact checks (pull_request) Successful in 38s
CI / DB access operator (pull_request) Successful in 1m11s
CI / Mac foundation hermetic checks (pull_request) Successful in 2m2s
CI / Docker image build (pull_request) Successful in 2m39s
CI / Root app checks (pull_request) Successful in 5m53s
CI / Required checks (pull_request) Successful in 11s
4cac05c8e7
- POST /api/flows/deploy-scrum4me/advise: eist een geslaagde dry-run van
  deploy_scrum4me van deze gebruiker en host, jonger dan 30 min; haalt de
  adviesinvoer via execAgentResult('scrum4me_deploy_advice_input') (code ≠ 0
  of geen JSON → 502 met stderr); bindt plan.generated_at aan het venster
  [started_at, ended_at ?? now] (anders 409); weigert overschrijven van
  toegepast advies (409); adviseDeploy + upsert DeployAdvice; bij een
  block-warning s4m_queue_notify_jp met idempotency-key
  deploy-scrum4me-advice:<advice_id> en de notice op stdin, fail-open
  (notify_error). Respons { advice_id, plan, input, advice, error_text,
  notify_error }.
- lib/deploy-advice/notify.ts: buildBlockNotice (zuivere module).
- POST /api/flows/run: plan_overrides { add_flags } en advice_id, alleen
  voor deploy_scrum4me (400); add_flags unieke vlaggen uit FLAG_NAMES (400);
  advice van deze gebruiker/host, < 30 min, nog niet toegepast (404/409);
  alle validatie vóór flowRun.create; daarna applied_flow_run_id zetten en
  plan_overrides naar de agent.
- Tests (base): deploy-advice-advise-route, flows-run-route-overrides.

IDEA-275 increment 2, spec/plan rev 2.

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

REQUEST_CHANGES

  • error — app/api/flows/run/route.ts:98 — De read op applied_flow_run_id en de onvoorwaardelijke update zijn niet atomair. Twee gelijktijdige requests lezen allebei null, maken elk een FlowRun en overschrijven dezelfde applied_flow_run_id. Een lokale reproductie geeft tweemaal 200 en twee verschillende run-id's in de updates. Ook als de agent één run weigert, kan de advieskoppeling van de werkelijk uitgevoerde run worden overschreven. Maak de claim conditioneel op applied_flow_run_id=null en combineer claim en FlowRun-create in één transactie; de verliezer moet 409 krijgen zonder weesrun. Bescherm ook advise/route.ts:119 tegen een upsert die na de langlopende adviseDeploy een inmiddels toegepast advies overschrijft. Voeg concurrentietests toe.
  • error — app/api/flows/deploy-scrum4me/advise/route.ts:113 — adviseDeploy redigeert een kopie voor de modelaanroep, maar deze route slaat de oorspronkelijke input inclusief commit-subjects op en retourneert die als input. Een subject met token=review-secret-value verschijnt ongewijzigd in DeployAdvice.input_json en de HTTP-respons (lokaal gereproduceerd). De migratie beschrijft juist redacted adviser input / never secrets. Gebruik één geredigeerde invoer voor model, opslag en respons; test dit op routeniveau, ook zonder API-key.

Plan gekoppeld via pr_refs: T-214, T-215, ST-080, ST-079, ST-081, PBI-26. Geen omitted-referenties; het meegeleverde plan_doc PBI-26 was afgekapt (truncated=true). De actuele IDEA-275-specificatie is aanvullend gelezen. De diff dekt de backend van ST-080; de overige agent-/UI-onderdelen behandel ik als vervolgwerk, niet als ontbrekende oplevering van deze PR. De racecondities doorbreken de eis dat toegepast advies niet opnieuw wordt gebruikt of overschreven.

Verificatie op commit 4cac05c8e7: vier nieuwe testbestanden, 29 tests geslaagd; Prisma-schema geldig. Twee aanvullende lokale reproducties bevestigen bovenstaande fouten. Typecheck niet groen door ontbrekende @s4m-kit-submodule, gegenereerde build-info en ops-agent-dependencies; geen aangetoonde regressie in de gewijzigde bestanden. Geen live deploy of echte model-/queue-aanroep uitgevoerd.

# REQUEST_CHANGES - **error — app/api/flows/run/route.ts:98** — De read op applied_flow_run_id en de onvoorwaardelijke update zijn niet atomair. Twee gelijktijdige requests lezen allebei null, maken elk een FlowRun en overschrijven dezelfde applied_flow_run_id. Een lokale reproductie geeft tweemaal 200 en twee verschillende run-id's in de updates. Ook als de agent één run weigert, kan de advieskoppeling van de werkelijk uitgevoerde run worden overschreven. Maak de claim conditioneel op applied_flow_run_id=null en combineer claim en FlowRun-create in één transactie; de verliezer moet 409 krijgen zonder weesrun. Bescherm ook advise/route.ts:119 tegen een upsert die na de langlopende adviseDeploy een inmiddels toegepast advies overschrijft. Voeg concurrentietests toe. - **error — app/api/flows/deploy-scrum4me/advise/route.ts:113** — adviseDeploy redigeert een kopie voor de modelaanroep, maar deze route slaat de oorspronkelijke input inclusief commit-subjects op en retourneert die als input. Een subject met token=review-secret-value verschijnt ongewijzigd in DeployAdvice.input_json en de HTTP-respons (lokaal gereproduceerd). De migratie beschrijft juist redacted adviser input / never secrets. Gebruik één geredigeerde invoer voor model, opslag en respons; test dit op routeniveau, ook zonder API-key. Plan gekoppeld via pr_refs: T-214, T-215, ST-080, ST-079, ST-081, PBI-26. Geen omitted-referenties; het meegeleverde plan_doc PBI-26 was afgekapt (truncated=true). De actuele IDEA-275-specificatie is aanvullend gelezen. De diff dekt de backend van ST-080; de overige agent-/UI-onderdelen behandel ik als vervolgwerk, niet als ontbrekende oplevering van deze PR. De racecondities doorbreken de eis dat toegepast advies niet opnieuw wordt gebruikt of overschreven. Verificatie op commit 4cac05c8e7b50a820d1ea18c4f6a3a26e7c155a6: vier nieuwe testbestanden, 29 tests geslaagd; Prisma-schema geldig. Twee aanvullende lokale reproducties bevestigen bovenstaande fouten. Typecheck niet groen door ontbrekende @s4m-kit-submodule, gegenereerde build-info en ops-agent-dependencies; geen aangetoonde regressie in de gewijzigde bestanden. Geen live deploy of echte model-/queue-aanroep uitgevoerd.
fix(deploy-advice): atomaire advies-claim en eenmalige redactie in de routes (review 1377, T-215, ST-080)
All checks were successful
CI / Select checks (pull_request) Successful in 38s
CI / Ops-agent checks (pull_request) Successful in 48s
CI / Deploy artifact checks (pull_request) Successful in 22s
CI / DB access operator (pull_request) Successful in 1m17s
CI / Mac foundation hermetic checks (pull_request) Successful in 1m55s
CI / Docker image build (pull_request) Successful in 3m3s
CI / Root app checks (pull_request) Successful in 6m35s
CI / Required checks (pull_request) Successful in 31s
76385c3eef
Codex-review 1377 op PR #293, twee blockers:

1. Race op applied_flow_run_id. Run-route: flowRun.create en de claim van het
   advies zitten nu in één prisma.$transaction met een conditionele
   updateMany (where applied_flow_run_id IS NULL); count 0 → eigen fout,
   transactie rolt terug (geen weesrun) en 409. Advise-route: de opslag na de
   langlopende adviseur-call is een conditionele updateMany op de onbetrokken
   rij, create als er nog geen rij is (P2002 → één keer opnieuw de update);
   een inmiddels toegepast advies wordt niet overschreven (409).
   lib/deploy-advice/claim.ts bundelt de claim-helper.
2. Ongeredigeerde invoer. De advise-route redigeert de adviseursinvoer één
   keer (lib/deploy-advice/redact.ts, zuivere module; advisor.ts gebruikt
   dezelfde functie) en gebruikt die kopie voor model, plan_json/input_json
   én de HTTP-respons, ook zonder API-key.

Tests: concurrentie in beide routetests (twee Deploys → één 200, één 409,
één agent-call; advies toegepast tijdens de adviseur-call → 409 zonder
create; verloren create-race → retry), redactietest (token=review-secret-
value komt niet in opslag of respons).

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

COMMENT

Geen blokkerende codebevindingen aangetoond. De implementatie sluit binnen de aangegeven PR-scope aan op ST-080/T-214/T-215 en de product-specificatie IDEA-275. Door de onvolledige onafhankelijke typeverificatie geef ik conform de safe-default geen APPROVED.

Findings

  • INFO — tsconfig.json:23 — Volledige typecontrole niet onafhankelijk bevestigd: de private submodule vendor/scrum4me-copilot voor @s4m-kit kan wegens ontbrekende authenticatie niet worden opgehaald. De eerste typecheck meldt daarnaast ontbrekende ops-agent-dependencies. Dit is een verificatiebeperking, geen aangetoond defect in deze diff.

Plan en scope

plan gekoppeld via pr_refs; references: T-214, T-215, ST-080, ST-079, ST-081, PBI-26. omitted is leeg; het meegeleverde PBI-26-plandocument is wel afgekapte tekst. De relevante volledige IDEA-275-specificatie is aanvullend gelezen via de product-docs.

De PR rondt expliciet ST-080 af. De ops-agent/queue-module (ST-079) en pagina/auditblok (ST-081) zijn afzonderlijke opleveringen; hun ontbreken is hier geen blokkerende finding.

Verificatie

  • PR open en head bevestigd: 76385c3eef927d4027a56ef479e3cc5ae656e011.
  • Vier nieuwe suites: 34/34 tests geslaagd.
  • Prisma generate en validate geslaagd; diff-whitespacecontrole geslaagd.
  • Typecontrole niet groen door bovengenoemde omgevingsafhankelijkheden; volledige build, volledige testsuite en hostintegratie niet uitgevoerd.

De review omvat SSE-contract, toegangs-/host-/leeftijdsvalidatie, planbinding, conditionele adviesopslag en transactieclaim, redactie, migratie en testregistratie.

# COMMENT Geen blokkerende codebevindingen aangetoond. De implementatie sluit binnen de aangegeven PR-scope aan op ST-080/T-214/T-215 en de product-specificatie IDEA-275. Door de onvolledige onafhankelijke typeverificatie geef ik conform de safe-default geen APPROVED. ## Findings - **INFO — tsconfig.json:23** — Volledige typecontrole niet onafhankelijk bevestigd: de private submodule `vendor/scrum4me-copilot` voor `@s4m-kit` kan wegens ontbrekende authenticatie niet worden opgehaald. De eerste typecheck meldt daarnaast ontbrekende ops-agent-dependencies. Dit is een verificatiebeperking, geen aangetoond defect in deze diff. ## Plan en scope plan gekoppeld via pr_refs; references: T-214, T-215, ST-080, ST-079, ST-081, PBI-26. `omitted` is leeg; het meegeleverde PBI-26-plandocument is wel afgekapte tekst. De relevante volledige IDEA-275-specificatie is aanvullend gelezen via de product-docs. De PR rondt expliciet ST-080 af. De ops-agent/queue-module (ST-079) en pagina/auditblok (ST-081) zijn afzonderlijke opleveringen; hun ontbreken is hier geen blokkerende finding. ## Verificatie - PR open en head bevestigd: `76385c3eef927d4027a56ef479e3cc5ae656e011`. - Vier nieuwe suites: **34/34 tests geslaagd**. - Prisma generate en validate geslaagd; diff-whitespacecontrole geslaagd. - Typecontrole niet groen door bovengenoemde omgevingsafhankelijkheden; volledige build, volledige testsuite en hostintegratie niet uitgevoerd. De review omvat SSE-contract, toegangs-/host-/leeftijdsvalidatie, planbinding, conditionele adviesopslag en transactieclaim, redactie, migratie en testregistratie.
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/Ops-dashboard!293
No description provided.