Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/archive/handoffs/HANDOFF-2026-05-26.md
T

18 KiB
Raw Blame History

Handoff — 2026-05-26

Historical/imported snapshot only (2026-05-25 cleanup). This file is preserved for audit/history even though its title is future-dated relative to 2026-05-25. Do not treat its "push", "deploy" or operator instructions as current work. Use PROGRESS.md, OPERATOR-CHECKLIST.md and the latest session notes for live status.

Vorgänger-Agent: Claude Opus 4.7 (1M context). Akkord-Lauf gegen HANDOFF-2026-05-25.md, Tasks A–G durchgezogen, gepusht und gegen Staging verifiziert.


1. Was tatsächlich landed (Task-für-Task)

Push: 30 Commits, d1b2183a..fb5736b6 main -> main. Lefthook pre-push (typecheck) durch. Coolify-Webhook hat NICHT automatisch deployed; alle drei Apps wurden manuell via GET /api/v1/deploy?uuid=… neu deployed und sind anschließend running:healthy.

  • 1d4e6cbe feat(auth): allow nullable User.passwordHash and route password-less users to magic-link
  • 084af35f docs(improvement-plan): mark #20 password-hash nullable as landed

Schema-Migration prisma/migrations/20260525000000_01_user_password_hash_nullable/migration.sql (ALTER TABLE "User" ALTER COLUMN "passwordHash" DROP NOT NULL). AuthService liefert für null-passwordHash-User jetzt { requiresMagicLink: true, magicLinkHref: "/forgot-password" } statt durch den Dummy-Hash zu fallen. API /v1/auth/login mirror'd den Guard mit generischem invalid_credentials (kein Account-Exists-Leak). i18n-Key errors.passwordlessAccountUseMagicLink neu in en/de auth.json. Neuer Vitest-Spec AuthService.passwordless.test.ts + Anpassungen an verifyPassword-Signatur (string | null akzeptiert deterministisch { valid: false }). 27/27 Auth-Suiten grün. Operator-Folgeschritt: prisma migrate deploy gegen Staging-DB (lief lokal nicht; nur Files committed).

Task B — #27 Password-Policy Login Soft-Banner

  • a1c4532b feat(auth): add password-policy soft-check banner after login
  • 8003c641 docs(improvement-plan): mark #27 password-policy login soft-banner as landed

Login-Action ruft nach erfolgreichem Credential-Verify validatePassword(plain, { email }) im Non-Throwing-Mode auf; bei !valid setzt sie das Session-Flag passwordPolicyOutdated. app.$tenant.tsx-Loader liest Session + pwPolicyRemindAfter-Cookie via neuem evaluatePasswordPolicyBanner-Helper und rendert PasswordPolicyBanner (Warn-Tone aus existierendem WarningBanner-Palette) oberhalb des <Outlet />. "Remind me in 7 days" geht an api.password-policy-remind Resource-Route, setzt Set-Cookie: pwPolicyRemindAfter=<ms>; Path=/; Max-Age=604800; SameSite=Lax und gibt 204 zurück. 18 neue Vitest-Tests (13 banner-decision + 3 AuthService-soft-check + 2 resource-route).

Task C — #39 Pub/Sub Reconnect-Flush + Testcontainers

  • 47c37b88 feat(shared-store): flush L1 caches on redis reconnect
  • f4b290bb test(shared-store): real-redis testcontainers integration for two-tier cache
  • 1f68080f chore(shared-store): rename unused buildClient role param to _role
  • deb45ffb docs(improvement-plan): mark #39 reconnect-flush + testcontainers landed

SharedStoreAdapter bekommt onReconnect(handler): () => void. RedisAdapter lauscht ioredis-'ready'-Event, überspringt den initialen Connect-Handshake und fanned subsequente Reconnects in registrierte Handler. MemoryAdapter no-op. createTwoTierCache().subscribe() registriert debouncten flushLocal() (default 1000 ms, konfigurierbar via reconnectFlushDebounceMs). Logger-Zeile auf INFO: "two-tier cache <namespace>: redis reconnected, L1 flushed". Neue Opt-in-Test-Suite two-tier-cache.testcontainers.test.ts mit drei Szenarien (cross-instance Fan-out, Reconnect-Flush, Peer-L2-Mutation-nach-Reconnect); lief live gegen redis:7-alpine (OrbStack), alle drei grün ~4 s. testcontainers@^10.28.0 als devDep des shared-store-Pakets. Detail-MD-Deviations: zwei Bullets als resolved markiert.

Task D — #42 Outbox (Stripe-Webhook + CLI + E2E)

  • 0bebef90 feat(outbox): migrate stripe webhook to outbox pattern
  • 9e40294f feat(cli): add outbox requeue command for failed and bulk replay
  • a5ac964b test(outbox): end-to-end integration via real postgres opt-in
  • e5cfaf93 docs(improvement-plan): record #42 stripe migration + cli + e2e

Stripe-Webhook in apps/api/src/billing/stripe-webhook-route.ts wrappt updateTenantSubscriptionProductFromStripe + publishOutboxEvent in ein einziges prisma.$transaction. Der frühere callLegacyEvent-Direkt-Aufruf lebt jetzt im neuen apps/worker/src/jobs/legacy-event-receiver.ts, geschützt durch withOutboxIdempotency. Bootstrap registriert den Receiver auf outbox.notification. CLI: toolctrl-cli outbox requeue --event-id=… (akzeptiert nur FAILED/DONE) und outbox requeue --type=… --since=… für Bulk. E2E-Suite packages/db/src/outbox-e2e.test.ts lief live gegen lokales Postgres (3/3 grün): Publisher → Dispatcher-Tick → Receiver schreibt Marker-Event, Idempotenz beim zweiten Tick verifiziert. 15 neue CLI-Tests, 9 Receiver-Tests. Deferred (mit Acceptance-Kriterien in der Detail-MD): WorkflowEngine-Migration, Mail/Webhook/Notification/Audit-Migrationen aus Web-Actions, Admin-UI /app/admin/outbox — jede Domain ein eigener Code-Review-Cycle. Foundation steht; die Folgeschritte sind mechanisch.

Superseded status note (2026-05-28): This archive entry reflects the 2026-05-26 handoff state. Later work reconciled the workflow-trigger/outbox path and worker bootstrap. Use current PROGRESS.md plus docs/ops/worker-queues.md for live workflow/outbox status.

Latent-Bug dokumentiert: publishOutboxEvent-Recovery-Pfad (Unique-Violation → findUnique innerhalb derselben Tx) funktioniert nicht in derselben Transaktion (PG markiert die Tx aborted). In Production ist jeder Publish eine eigene Tx, deshalb harmlos. Nicht gefixt.

Task E — #76 Coverage-Gates Audit + targeted wins

  • 29736f59 chore(coverage): backfill per-module gate entries for untracked packages
  • d0478a73 docs(testing): record 2026-05-25 critical-path coverage baseline
  • 9f86f2d1 test(api/auth): graduate apps/api/src/auth coverage gate to 99/92
  • fd7a23cc test(entitlements): graduate packages/entitlements coverage gate to 96/90
  • 3f5ecd15 docs(testing): publish coverage-sprint backlog for #76 follow-up sessions
  • a532c8cb docs(improvement-plan): #76 baseline + backlog landed; sprint still deferred
  • b1155126 chore(coverage): pin new-entry gates to current achievement levels

scripts/coverage-targets.json erweitert auf 50 Einträge (vorher 22 — 28 untracked Packages bekamen konservative Baselines mit sprintTarget 80). 2026-05-25-Baseline mit per-Modul-Tabelle in docs/testing/coverage-baseline-2026-05-25.md, sortiert nach kleinstem Gap zu sprintTarget. Zwei Critical-Path-Module von "graduated" auf gebumptes Gate gehoben: apps/api/src/auth (99.2 % stmt / 92.2 % br) und packages/entitlements (97.0 % / 90.8 %). Backlog-File docs/testing/coverage-sprint-backlog.md für die nächste Session — größte Lücken: apps/web/app/utils/db/tenants.db.server.ts (2.9 %), apps/web/app/utils/stripe.server.ts (3.5 %), apps/web/app/utils/db/permissions/** (15.9 %). Coverage-Run-Budget: ~136 s.

In passing entdeckt: pnpm test und der Coverage-Gate laufen auf unterschiedlichen Scopes; drei Test-Failures (apps/api/src/app.test.ts Stripe-Webhook, packages/config/src/env-examples.test.ts, packages/cli/src/commands/tenant/json-codec.test.ts Buffer JSON) tauchen nur unter Coverage auf. Documented im Backlog, nicht gefixt.

Task F — #62 Storybook (Toolbar-Globals + Tailwind v4 + Baselines)

  • 76732977 feat(storybook): add locale + theme toolbar globals with i18n decorator
  • 24ee3bd9 build(storybook): wire real tailwind v4 + project token css pipeline
  • d370c5a3 chore(storybook): commit lost-pixel baseline snapshots
  • 30435fbb docs(improvement-plan): record #62 toolbar-globals + tailwind + baseline progress

Locale-Toolbar-Global (en/de) verdrahtet via @storybook/addon-themes mit react-i18next-Instanz; Translation-Files lazy via import.meta.glob aus apps/web/public/locales/**. Theme-Switch bleibt am bestehenden withThemeByClassName-Decorator (Single Source of Truth). Tailwind-v4-Pipeline lief auf Anhieb sauber: viteFinal-Hook lädt @tailwindcss/vite, preview.css @import "tailwindcss" + @custom-variant dark — pnpm --filter @toolctrl/storybook build-storybook exit 0 in 3 s. 67 Lost-Pixel-Baseline-PNGs (~800 kB) unter apps/storybook/.lostpixel/baseline/; Re-Run visual-regression 67/67 no-diff. Einmaliges Bootstrap nötig: node …playwright-core/cli.js install chromium-headless-shell (system-cache hatte v1217/1169, lost-pixel braucht v1223) — dokumentiert. Deferred (Acceptance je 1 Zeile in Detail-MD): Brand- + ui-layer-Toolbar-Globals (keine Stories nutzen sie heute), Coolify static-deploy (storybook.staging.toolctrl.de, operator-only), Migration der 21 Demo-Primitive-Stories auf echte Components.

Task G — Tenant-Snapshot Global-Row Extractor (#44 B7-Limit)

  • e9fe18fc feat(cli): enumerate globals referenced by tenant-scoped models
  • 6e0aafa3 feat(cli): include globals/.jsonl in tenant snapshots
  • a4cdf6ef feat(cli): replay globals first on tenant restore with upsert/skip/error modes
  • 27cad89d test(cli): round-trip restore into truly empty pgvector DB
  • fb5736b6 docs(ops): close tenant-snapshot globals design-limit (#44 Task G)

User ist der einzige extrahierte Global (38 FK-Spalten aus 31 tenant-scoped Models in GLOBAL_REFERENCED_MODELS). Sieben weitere FK-Targets (Entity, EntityGroup, Formula, Onboarding, PromptFlow, RowComment, WorkflowBlock) sind als PLATFORM_CATALOG_GLOBALS deklariert und bewusst nicht im Snapshot — sie werden per Migration/Setup einmal pro Deployment geseeded. Test models.test.ts:73-95 parsed jede Schema-FK-Relation und failed CI wenn ein neuer Global nicht explizit in eine der zwei Listen einsortiert wird. Restore-Flag --globals=upsert|skip|error (default upsert). Anonymizer scrubt email, firstName, lastName, phone, avatar plus credentials (passwordHash, Verify-Token, OAuth-IDs, TOTP-Secrets, MFA-Recovery-Codes). Round-Trip-Integration-Test lief live gegen zwei pgvector-Container (pgvector/pgvector:pg16 auf 55801/55802), 138 Migrationen applied, 365/365 grün — die 6 vorher-broken Models (TenantUser/TenantIpAddress/UserRole/Event/Log/SupportTicket) restoren clean. Runbook docs/ops/tenant-snapshot.md Sektion umbenannt von "Restore prerequisites: global rows are NOT in the snapshot" zu "How globals are handled in restore" mit Mode-Tabelle + Backward-Compat-Hinweis (Pre-Task-G-Snapshots ohne globals/ werden mit Warning weiterhin akzeptiert).


2. Deploy + Verifikation

Push: d1b2183a..fb5736b6 main -> main, 30 Commits. Lefthook pre-push (i18n 0.76 s + typecheck 39.01 s) grün.

Gitea: git ls-remote origin main → fb5736b63f81c48fca801b35e18f9cc990d79f25. HEAD synchron.

Coolify-Deploy: Webhook hat NICHT automatisch deployed (alle drei Apps standen noch auf d1b2183a mit is_webhook: false als jüngste Deployments). Manuell getriggert via GET /api/v1/deploy?uuid=… mit Bearer-Token aus ~/.cli-tokens/coolify-token. Alle drei Deploys reached status: finished innerhalb ~3 Minuten. Final-Status alle running:healthy:

  • boilerplate-web (mrf8lj70kmy9hqprx9dd6w7q) — Container …-045356223784, Up About a minute (healthy)
  • boilerplate-api (e109dzc3xzjxi54llfje4tob) — Container …-045356524191, Up About a minute (healthy)
  • boilerplate-worker (k6cibn0rkrrl7izw970ao1l4) — Container …-045416128858, Up About a minute (healthy)

2026-05-26 status note: this three-app deploy observation is historical. Current deploy docs supersede the single boilerplate-worker setup with five persistent Coolify worker applications: worker-general, worker-mail, worker-import, worker-webhook, and worker-plugin. worker-mail owns WORKER_QUEUE_GROUP=mail; use docs/ops/worker-queues.md, docs/worker.md, and docs/deployment.md as the current topology sources.

Open Frage für Operator: Warum hat der Gitea-Webhook nicht ausgelöst? Vorherige Deploys (535, 536, 537 vom 2026-05-24 00:31) waren ebenfalls is_webhook: false. Coolify-Auto-Deploy-Toggle in der UI prüfen oder Gitea-Webhook-Logs.

Smoke-Tests (HTTP):

  • GET https://boiler.saas-ctrl.com/login → 200, HTML enthält <title>Anmelden | Boilerplate</title> + name="email" + name="password"
  • GET https://boiler.saas-ctrl.com/healthz → 200
  • GET https://api.boiler.saas-ctrl.com/healthz → 200
  • GET https://api.boiler.saas-ctrl.com/v1/health → 200
  • GET https://admin.boiler.saas-ctrl.com/ → 302 (Login-Redirect, erwartet)
  • app.boiler.saas-ctrl.com — keine Antwort; Subdomain existiert evtl. nicht, alle tenant-Routes laufen unter boiler.saas-ctrl.com/app/<tenant>. Nicht weiter verfolgt.

Smoke-Test (Browser, Playwright): boilerplate-staging-admin-Credentials genutzt, Chromium headless. Login-Form ausgefüllt, submit → keine MFA-Prompt (TOTP-Secret war verfügbar, aber Server fragte nicht) → final URL https://admin.boiler.saas-ctrl.com/dashboard, Title Dashboard | Boilerplate. Screenshots:

  • /tmp/staging-smoke-01-login.png (Login-Form, 29 kB)
  • /tmp/staging-smoke-03-dashboard.png (Admin-Dashboard nach Login, 160 kB)

Hinweis: MFA wurde nicht abgefragt obwohl der Account ein TOTP-Secret hat. Entweder ist MFA für Staging-Admin in der DB nicht aktiviert, oder es gibt einen Remember-Me-State im Browser-Context. Nicht weiter untersucht — Login-Flow ist funktional.


3. Was deferred wurde + Grund

Task D — bewusst nicht in dieser Session

  • Admin-UI /app/admin/outbox — Operator-Handoff sagt explizit "Bewusst raus: Design-Entscheidung"
  • WorkflowEngine-Trigger-Migration (Step 6) — eigene Engine-Semantik, eigener Code-Review-Cycle
  • Mail/Webhook/Notification/Audit-Migration aus Web-Actions (Steps 7-9) — pro Domain ein Migration-Commit + Receiver-Worker, jeweils mit Playwright-Assertion (Worker-Crash zwischen DB-Commit und Queue-Pop liefert Side-Effect nach Restart). Foundation steht; mechanisch.

Superseded status note (2026-05-28): WorkflowEngine-trigger migration is no longer represented solely by this deferred list. Check current progress and worker queue docs before treating this archive as actionable work.

Task E — Coverage-Sprint

Die 2-3-Wochen-Sprint-Arbeit (Steps 4-12 der Detail-MD) ist explizit weiter deferred-with-backlog. Größte Lücken zu Critical-Path-Sprintzielen:

  • apps/web/app/utils/db/tenants.db.server.ts — 92.1 pp Statement-Gap
  • apps/web/app/utils/stripe.server.ts — 81.5 pp
  • apps/web/app/utils/db/permissions/** — 74.1 pp
  • apps/api/src/billing — 12.9 pp Branch-Gap (stmt past)
  • apps/api/src/isolation — 23.3 pp Branch-Gap (stmt 100 %)

Backlog mit One-Line-Hints in docs/testing/coverage-sprint-backlog.md. Drei Test-Failures unter Coverage-Scope (siehe Task-E-Block) sollten zuerst gefixt werden — sonst kann der Gate-Script nicht zu Ende laufen.

Task F — Storybook

  • Brand- + ui-layer-Toolbar-Globals — werden no-op solange keine Story sie nutzt
  • Coolify static-deploy für storybook.staging.toolctrl.de — Operator-Auth
  • Demo-Primitive-Stories → echte Components migrieren — Tailwind-Pipeline ist jetzt da, also unblocked

Pre-existing Failures (unverändert)

  • apps/web/app/application/ui/uiInventory.test.ts > maps all stable registry surface, action and nav IDs — vom Operator dokumentiert als "allowed pre-existing"; nicht angefasst
  • Drei Coverage-only-Failures siehe oben

2026-05-26 status note: this failure list is historical. A later focused run of the listed coverage-only suites plus packages/ai/src/index.test.ts passed (200 tests total), and PROGRESS.md now records that those coverage-only failures no longer reproduce.


4. Was als Nächstes ansteht

Geordnet nach Wert × Risiko-niedrig:

  1. prisma migrate deploy gegen Staging-DB für Task A. Schema-Migration 20260525000000_01_user_password_hash_nullable ist nur committed, nicht angewandt. Bis dahin ist der passwordHash-Spalt in Staging weiter NOT NULL, der neue Code arbeitet aber gegen ein nullable-erwartendes Schema. Funktional kein Bruch (alle existierenden User haben einen Hash), aber sauberer wäre apply.

  2. Coolify Gitea-Webhook reparieren. Auto-Deploy hat in dieser Session nicht ausgelöst. Mögliche Ursachen: Webhook-URL-Drift in Gitea, Auto-Deploy-Toggle in Coolify aus, Webhook-Secret-Mismatch. Bis dahin müssen Deploys manuell getriggert werden.

  3. Outbox-Migrationen schrittweise nachziehen. Mail/Webhook/Notification/Audit pro Domain ein PR. Acceptance pro PR siehe docs/improvement-plan/03-scaling-infrastructure/outbox-pattern.md "Deviations from Plan".

  4. Coverage-Sprint-Backlog abarbeiten. Eine eigene Session pro Critical-Path-Modul, starten bei apps/api/src/isolation (kleinster Branch-Gap, Stmt-Coverage schon 100 %).

  5. Storybook: echte Components statt Demo-Primitives. Tailwind-Pipeline ist da, Lost-Pixel-Baseline existiert — Migration ist jetzt sicher.

  6. Coolify-Static-Site storybook.staging.toolctrl.de — Operator-Setup.


5. Misc

  • 30 Commits durchgängig mit Co-Authored-By: Claude Opus 4.7 (1M context) Trailer.
  • Lefthook pre-commit (test-density, eslint-baseline, lint-staged, secrets) lief auf jedem Commit grün.
  • Keine generierten Prisma-Client-Files committed; git status zeigt vor + nach Push den gleichen Set von 9 modified + 1 untracked unter packages/db/generated/.
  • Live-Integration-Tests gegen Docker liefen für Task C (Redis), Task D (Postgres), Task G (zwei pgvector-Container).
  • docs/improvement-plan/PROGRESS.md Row-Aktualisierungen pro Task durchgeführt.

6. 2026-05-25 Follow-up Sync

  • Generated Prisma client drift from this handoff was committed in 98d42332 (chore: sync generated prisma client); worktree was clean afterward.
  • Persistent Coolify worker-group provisioning closed B-014: staging now runs separate persistent general, mail, import, webhook, and plugin worker apps. This supersedes the earlier three-app deploy observation. #19 Magic-Link Secondary-Flow is marked completed because toolctrl.email jobs no longer require a manual temporary mail worker.
  • Operator/checklist docs were bucket-synced: A has 3 open quick wins, B has 7 open medium operator items, C has 3 long-running external items, and D has 8 remaining engineering-polish sprints after D7/D8 closure.

Ende.