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

19 KiB

Handoff — Stand 2026-05-25 (Autonomer Nacht-Modus, Nonstop)

Historical snapshot only (2026-05-25 cleanup). This file is preserved for audit/history. Do not treat its "nonstop", "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) Letzte aktive Session: B7-Tenant-Snapshot-Verify komplett durchgezogen, alle vier losen Enden aus dem 2026-05-24-Handoff geschlossen.

Historical request captured verbatim for audit, superseded by the warning above: "Operator schläft. Du arbeitest NONSTOP an dem Plan in Section 2, machst alles durch was du machen kannst, deployst am Ende selbst und verifizierst gegen Coolify + Gitea + Browser."


0. Start hier (5-Minuten-Onboarding, dann SOFORT loslegen)

Lies in dieser Reihenfolge:

  1. Dieses Dokument komplett bis zum Ende.
  2. HANDOFF-2026-05-24.md für den davor liegenden archivierten Stand (Bucket-1-Abbau, zentrale Observability-Infra).
  3. .claude/CLAUDE.md — React-Router-v7-Konventionen sind hart enforced.
  4. Wenn du Infra anfasst: toolctrl-labs/infra auf Gitea (git clone https://git.tool-ctrl.de/toolctrl-labs/infra), README + STANDARDS.

Sofort-Sanity-Check:

git log --oneline -7
# HEAD muss d6e19aab sein (dieses handoff)
# d6e19aab docs(handoff): 2026-05-25 — akkord-modus for nightshift agent
# 377b96a4 feat(cli): wire tenant snapshot/restore + fix B7 PII gaps
# 12f23558 docs(handoff): 2026-05-24 — central observability + Sentry + Meili + Loki
# fa8b0e70 test(i18n): add e2e locale-switch coverage and label the locale picker (#72)
# a3885ed5 feat(i18n): split billing/crm/auth/emailMarketing into per-area namespaces (#72)

git status -s              # erwartet: nur packages/db/generated/** churn
git pull --rebase --autostash

Push-Status zum Sessionsstart: 5 lokale Commits liegen vor origin/main. Der Operator hat den Push aus dieser Session ausdrücklich an DICH delegiert — pushe sie GEMEINSAM mit deiner eigenen Arbeit ganz am Ende (siehe Section 4 „Deploy + Verifikation").


1. Was die letzte Session erledigt hat

1.1 B7 — Tenant-Snapshot-Verify (vollständig)

War der einzige echt offene Punkt aus Bucket 1. Drei Befunde:

A) Wiring-Lücke geschlossen. Die tenant snapshot/tenant restore-Citty-Commands waren reine Arg-Validators. Jetzt:

  • packages/cli/src/commands/tenant/prisma-runner.ts — PrismaRunner + PrismaRestoreRunner gegen @toolctrl/db. Cursor-Pagination (PK id, TenantSettingsRow cursor tenantId).
  • packages/cli/src/commands/tenant/json-codec.ts — JSON-Replacer für Date/BigInt/Buffer/Decimal (über this[key]-Trick um toJSON-Mangling zu umgehen) plus DMMF-freie Schema-Parser für Decode.
  • packages/cli/src/commands/tenant/env.ts — BACKUP_*-Env-Resolver tailored auf Tenant-Ops (S3 + Encryption optional).
  • Snapshot/Restore-Commands rufen jetzt echte Runner auf.

B) PII-Leaks im Anonymizer gefunden. Real-Tenant-Snapshot gegen Staging-DB demo-pro-crm per SSH-Tunnel ergab 2 plaintext-Email-Leaks:

  • SupportTicket-Map referenzierte schemafremde Keys title/description statt subject/message; fromEmail + fromUrl waren ungemappt.
  • Event-Map referenzierte payload statt des realen Feldes data.

Beide gefixt. Neuer Snapshot grep-clean.

C) Restore-Design-Limit dokumentiert. Restore in leere DB scheitert für 6 Modelle (TenantUser, TenantIpAddress, UserRole, Event, Log, SupportTicket — 32 Rows) wegen FK auf globales User-Model. Runbook docs/ops/tenant-snapshot.md erweitert um „Restore prerequisites: global rows are NOT in the snapshot". 6/12 Modelle mit Rows restoren clean. Dieses Limit ist Task G in deinem Akkord-Plan.

Commit 377b96a4. 317/319 Unit-Tests grün. Typecheck grün. PROGRESS.md Row #44 erweitert.

1.2 Vier lose Enden geschlossen

  • Altes Sentry auf boilerplate-staging runter, RAM 24Gi → 4.6Gi.
  • Marketing-VM im Mesh als 10.42.0.5, up=1 beide Jobs, infra-Repo Commit 66f1357 schon gepusht.
  • 63 Coolify-Env-Duplikate weg, kein Redeploy ausgelöst.
  • Coolify-Token liegt unter ~/.cli-tokens/coolify-token, API auf http://195.201.133.26:8000/api/v1.

2. Historical Arbeitsplan — superseded

2.1 Goldene Regeln (jede einzelne ist nicht verhandelbar)

  1. STOPPE NICHT bevor jeder Task in Section 2.2 entweder fertig committed ist oder als „nicht machbar" mit klarer Begründung in PROGRESS.md vermerkt ist. Wenn ein Task hängt — überspringe ihn, notiere warum, mache mit dem nächsten weiter. KEINE Pausen für Rückfragen, KEINE „darf ich…" — du hast volle Entscheidungsbefugnis innerhalb dieser Regeln.
  2. NUTZE TaskCreate / TaskUpdate / TaskList kontinuierlich. Als allererstes nach dem Sanity-Check legst du für JEDEN Task in 2.2 ein TaskCreate an (status pending). Du markierst jeden als in_progress bevor du anfängst, completed wenn du fertig bist. Lass die Liste durchgängig aktuell — sie ist deine eigene Spur.
  3. NUTZE SUBAGENTS aggressiv. Pro Task ist ein Subagent-Vorschlag in 2.2 angegeben. Wenn du Plan brauchst weil unklar — spawn Plan. Wenn du parallel arbeiten kannst — spawn mehrere general-purpose in einem Tool-Use-Block. Wenn du suchst — spawn Explore statt selbst zu greppen. Subagents geben dir Zusammenfassungen ohne deinen Kontext zu fluten.
  4. ATOMARE COMMITS pro Task. Eine logische Änderung pro Commit. Co-Author-Trailer auf Claude. Conventional-Commit-Prefix. Lefthook läuft pre-commit, lass den durch — wenn er rot wird, fixe was er findet und re-committe, gib nicht auf.
  5. PUSHE ERST AM ENDE. Alle deine Commits + die 5 schon-lokalen werden in EINEM Push am Schluss rausgeschickt, GEFOLGT VON Coolify-Deploy-Verifikation. Details in Section 4.
  6. PROGRESS.md nach jedem fertigen Task updaten (Datum, Commit-Hashes, was tatsächlich landed, was deferred wurde und warum). Eine Zeile pro Task reicht wenn das in die existierende Row paßt.
  7. NIEMALS git add -A — explizite Paths. packages/db/generated/** NIEMALS mitcommitten.
  8. Kein UI-Design-Urteil treffen. Wenn ein Task „wie soll das aussehen?" verlangt: vorhandene UI-Primitives aus packages/ui recyclen, nichts Neues erfinden. Banner-Texte, Button-Labels — nimm das Offensichtliche (englisch oder das was die Codebase vorhandene Strings hat).
  9. Tests müssen grün bleiben. pnpm test + pnpm typecheck müssen vor jedem Commit grün sein. Lefthook erzwingt typecheck pre-push.
  10. React Router v7 Konventionen einhalten — Route-Type-Imports IMMER ./+types/<name>, nie relativ.

2.2 Tasks — in dieser Reihenfolge

Lege als ALLERERSTES TaskCreate für jeden dieser sieben Tasks an. Markiere in_progress bevor du startest, completed wenn der Commit liegt.

Detail-MD: docs/improvement-plan/01-tech-debt-foundation/magic-link-invitation.md Subagent: general-purpose. Optional Plan vorab für Migration-Strategie. Was zu tun:

  1. Prisma-Migration User.passwordHash String? (nullable). Existierende Hashes NICHT touchen.
  2. Auth-Boundary: Login mit null passwordHash → Magic-Link-Flow statt 401.
  3. Invitation-Flow: neuer User ohne passwordHash, sofort Magic-Link statt Passwort-Setzen-Email.
  4. Tests: bestehende Login-Tests grün, neue Tests für null-passwordHash-Pfad. Akzeptanz: typecheck + tests grün, Detail-MD Progress-Log erweitert, PROGRESS Row updated. Achtung: User mit null passwordHash dürfen NICHT plötzlich passwortlos einloggbar werden wenn sie nicht explizit invited sind. Prüfe einen „wurde-eingeladen"-Marker, nicht nur das null.

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

Detail-MD: docs/improvement-plan/01-tech-debt-foundation/password-policy.md Subagent: general-purpose. Was zu tun:

  1. Banner-Komponente die nach Login eingeblendet wird wenn das aktuelle Passwort die neue Policy nicht erfüllt. Vorhandene packages/ui-Primitives nutzen, nichts Neues designen.
  2. Dismissible + „Remind me in 7 days"-Pattern aus Detail-MD.
  3. Server-side: welche User-IDs „policy-non-compliant" sind (Funktion vermutlich da).
  4. Tests für visible/dismissed States. Akzeptanz: Banner zeigt bei schwachem-Hash-Test-User, verschwindet nach Dismiss + Reload für 7 Tage.

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

Detail-MD: docs/improvement-plan/03-scaling-infrastructure/pubsub-cache-invalidation.md Subagent: Explore vorab um aktuellen Reconnect-Pfad zu kartieren, dann general-purpose. Was zu tun:

  1. Bei Redis-Reconnect: lokale Cache-Einträge die zwischen Disconnect und Reconnect entstanden sein könnten flushen (oder invalidate-all auf Subscription-Channel-Topic).
  2. Integrationstest mit testcontainers (Redis im Container starten, Verbindung killen, neue starten, asserten dass stale Reads weg sind).
  3. Opt-in-Pattern wie packages/db/src/outbox-claim.test.ts (env PUBSUB_TEST_REDIS_URL o.ä.). Akzeptanz: Test grün lokal mit Container, skipped ohne env.

Task D — #42 Outbox-Completion (ohne Admin-UI)

Detail-MD: docs/improvement-plan/03-scaling-infrastructure/outbox-pattern.md Subagent: Plan vorab (Task ist groß) → dann mehrere general-purpose in Wellen (Call-Site-Migrationen können parallel). Scope:

  1. Call-Site-Migrationen: jeden Outbox-Producer aus der Detail-MD auf outboxDispatch umstellen.
  2. CLI toolctrl-cli outbox requeue --event-id=X und outbox requeue --type=Y --since=Z.
  3. E2E: Producer schreibt Event → Worker dispatcht → Receiver empfängt → AuditEvent. Bewusst raus: Admin-UI (/app/admin/outbox) — Design-Entscheidung. Detail-MD annotieren („Admin-UI deferred — needs UX input").

Task E — #76 Test-Coverage Per-Modul-Gates

Detail-MD: in docs/improvement-plan/ — selbst finden (grep -r "coverage" docs/improvement-plan o.ä.). Subagent: Explore für Coverage-Status pro Modul, dann general-purpose pro Modul. Was zu tun:

  1. Per-Modul Coverage-Gates aktivieren (vitest config in jedem Paket).
  2. Kritische-Pfad-Module auf 85-95% hochziehen — Liste in Detail-MD.
  3. Fehlende Tests schreiben statt Coverage künstlich drücken. NICHT in packages/db/generated/** testen, NICHT Mocks-only. Akzeptanz: Per-Modul-Gates aktiv und grün.

Task F — #62 Storybook Lost-Pixel Setup

Detail-MD: docs/improvement-plan/08-mobile-cli-storybook-sdk/storybook.md Subagent: general-purpose. Was zu tun:

  1. lost-pixel als CI-Step gegen Storybook-Builds.
  2. Toolbar-Globals (i18n-Locale-Switch, Theme-Switch) als Decorators.
  3. Tailwind-v4-Pipeline für Storybook sauber.
  4. Baseline-Snapshots committen. Bewusst raus: neue Stories schreiben.

Task G — Globaler-Row-Extractor im Tenant-Snapshot (schließt B7-Limit)

Detail-MD: docs/improvement-plan/03-scaling-infrastructure/tenant-snapshot.md (eigene Section am Ende ergänzen) Subagent: Plan für Design (welche globalen Models? User zwingend, weitere?), dann general-purpose. Was zu tun:

  1. Beim Snapshot referenzierte User-Rows (+ andere globals nach Bedarf) mitextrahieren. Neuer Top-Level-Manifest-Eintrag globals/User.jsonl (cleaner als ins existierende Schema integrieren).
  2. Restore: globals ZUERST replayen (FK-Reihenfolge), dann tenant-scoped.
  3. Anonymizer-Coverage für neue globale Felder (User hat email, firstName, lastName, phone, etc. — alle anonymisieren).
  4. Round-Trip-Integration-Test erweitern: Restore in WIRKLICH leere DB muss jetzt grün sein für alle 12 Models.
  5. Runbook „Restore prerequisites"-Sektion entschärfen. Akzeptanz: Lokaler Round-Trip-Test gegen zwei frische pgvector-DBs ohne Vorab-Seed schreibt jetzt alle Models clean. PROGRESS Row #44 entsprechend aktualisieren.

2.3 Tabu — auf keinen Fall anfangen

  • #19 Magic-Link-Reset live-verify (braucht echte Email).
  • #26 TOTP-MFA live-verify (braucht echten Authenticator).
  • #38 Shared-Store async Session (höchstes Risiko, Operator-anwesend zwingend).
  • #53 / #55 / #59 (UI-Design-Entscheidungen).
  • #21 / #22 Plugin Phase 1+2 (Cure53-Audit-Block — Erweiterung jetzt sinnlos).
  • #73 WCAG P2 (Einzelfall-Urteile).
  • #17 FileObject-Scan-Columns (zu groß, eigene Session).
  • Worker-Groups Coolify-Services (Coolify-Service-API kann Live-Apps stören — Operator macht händisch).

Wenn ein Task in 2.2 nicht funktioniert: ÜBERSPRINGEN, in PROGRESS.md mit Begründung notieren, NÄCHSTEN nehmen. Nicht hängenbleiben.


3. Tools die du nutzen sollst

  • TaskCreate / TaskUpdate / TaskList: deine Aufgaben-Liste mit Checkboxen. Pflicht für Section 2.2.
  • Agent-Tool (Subagents): Plan für Architektur-Fragen, Explore für Codebase-Suchen, general-purpose für Implementierung. Parallel-Spawn in einem Tool-Use-Block wenn unabhängig.
  • Bash: für git, pnpm, ssh, docker, curl, prisma-Migrationen.
  • Read / Edit / Write: für Code-Änderungen.
  • Playwright (CLI über Bash) für Browser-Smoke am Ende — siehe Section 4.
  • gsd-Skills wo passend (z.B. gsd-add-tests wenn du nach einem Großtask Tests nachholen willst). Skill-Liste siehst du in deinem System-Prompt.

4. Deploy + Verifikation am Ende (PFLICHT)

Wenn alle Tasks aus 2.2 entweder completed oder „deferred mit Begründung" sind, mach das hier — auch das im Akkord ohne Stop:

4.1 Pre-flight

cd /Users/raffaelsheikh/Documents/GitHub/boilerplate
git status -s                              # Working tree sauber (nur generated churn)
git log --oneline origin/main..HEAD        # zeigt deine Commits + die 5 aus der vorigen Session
pnpm typecheck                              # muss EXIT=0 sein
pnpm test                                   # alle suites grün

Wenn typecheck oder tests rot sind: fixe es. Push NICHT mit rotem Code.

4.2 Push

git push origin main 2>&1 | tee /tmp/push.log

Push triggert Gitea-Webhook → Coolify-Auto-Deploy für die 3 boilerplate-Apps (web/api/worker). Lefthook pre-push fährt nochmal pnpm typecheck (~50s).

4.3 Coolify-Deploy verifizieren

TOKEN=$(cat ~/.cli-tokens/coolify-token)
for app in mrf8lj70kmy9hqprx9dd6w7q e109dzc3xzjxi54llfje4tob k6cibn0rkrrl7izw970ao1l4; do
  echo "== $app =="
  curl -s -H "Authorization: Bearer $TOKEN" \
    "http://195.201.133.26:8000/api/v1/applications/$app" \
    | python3 -c "import sys,json; d=json.load(sys.stdin); print('status:', d.get('status'), 'last_online_at:', d.get('last_online_at'))"
done

Status muss running:healthy werden für alle 3. Wenn ein Deploy hängt: warte aktiv per Polling (until <check>; do sleep 10; done-Pattern, NICHT mit kurzen sleeps zwischen Bash-Calls — Harness blockt das, nutze Monitor-Tool für lange Waits oder eine until-Schleife in einem einzelnen Bash-Call). Wenn Deploy nach 10 min nicht grün: in PROGRESS.md klar dokumentieren, im Coolify-UI-Frontend (über den Operator) zu untersuchen.

Container-Restart-Verifikation:

ssh boilerplate-staging "for c in mrf8lj70kmy9hqprx9dd6w7q-003059987808 e109dzc3xzjxi54llfje4tob-003103228130 k6cibn0rkrrl7izw970ao1l4-003119324400; do echo \"\$c: \$(docker inspect \$c --format '{{.State.Status}} since {{.State.StartedAt}}')\"; done"

(Container-Namen ändern sich pro Deploy — falls die alten weg sind, docker ps --format '{{.Names}}' für die neuen, dann obigen Befehl darauf.)

4.4 Gitea Push verifizieren

curl -s "https://git.tool-ctrl.de/toolctrl-labs/boilerplate/commits/branch/main" | grep -oE "377b96a4|d6e19aab|<dein-letzter-commit-hash>" | head

(Oder kurzer ssh-check: ssh git.tool-ctrl.de "cd /var/lib/gitea/git/toolctrl-labs/boilerplate.git && git log --oneline main -5" — Path kann abweichen.)

4.5 Browser-Smoke gegen Live-Staging

Playwright-Config liegt in /Users/raffaelsheikh/Documents/GitHub/boilerplate/playwright.config.ts. Staging-URL ist https://boiler.saas-ctrl.com (web), https://admin.boiler.saas-ctrl.com (admin), https://app.boiler.saas-ctrl.com (tenant-app falls separat).

Mindest-Smoke-Tests:

  1. Login-Page lädt: curl -sI https://boiler.saas-ctrl.com/login | head -3 → HTTP 200.
  2. Login-Flow mit Test-Credentials (Operator-Admin steht in ~/.cli-tokens/boilerplate-staging-admin): Playwright-Skript das login → Dashboard sieht → Screenshot ablegt. Skript kannst du ad-hoc schreiben, z.B.:
    import { chromium } from "playwright";
    const b = await chromium.launch();
    const p = await b.newPage();
    await p.goto("https://boiler.saas-ctrl.com/login");
    await p.fill('input[name="email"]', process.env.SMOKE_EMAIL!);
    await p.fill('input[name="password"]', process.env.SMOKE_PASSWORD!);
    await p.click('button[type="submit"]');
    await p.waitForURL(/dashboard|app|home/);
    await p.screenshot({ path: "/tmp/staging-smoke.png" });
    await b.close();
    
    Run: SMOKE_EMAIL=... SMOKE_PASSWORD=... pnpm tsx /tmp/smoke.ts
  3. Healthcheck-Endpoint falls vorhanden: curl -s https://boiler.saas-ctrl.com/api/healthz (oder /health — selbst finden).
  4. Sentry frisst Events: schmeiß einen synthetischen Error via curl -X POST https://boiler.saas-ctrl.com/api/_diag/throw (falls so ein Endpoint existiert, sonst Login-mit-falschem-Passwort und das wird im Sentry sichtbar). Verifiziere im zentralen Sentry-UI ist eher Operator-Job, aber dass der Request mind. HTTP-Antwort gibt zeigt der curl.

Wenn Smoke-Tests rot werden: in PROGRESS.md notieren, ein Rollback-Plan ist Operator-Entscheidung — NICHT alleine rollbacken.

4.6 Final-Handoff schreiben

Schreib einen neuen HANDOFF-2026-05-26.md (oder das aktuelle Datum, falls dein Lauf länger geht) mit:

  • Was tatsächlich landed (Task-für-Task mit Commit-Hash)
  • Was deferred wurde + Grund
  • Smoke-Test-Ergebnisse (Screenshots-Pfade, curl-Outputs)
  • Was als Nächstes ansteht
  • Commit + push das Handoff auch (es ist Teil deiner Auslieferung)

5. Wenn etwas Unerwartetes passiert

Du stoppst trotzdem nicht. Stattdessen:

  • Task überspringen, in PROGRESS.md eintragen warum, weiter mit nächstem.
  • Wenn ein push fehlschlägt (z.B. lefthook blockt wegen typecheck): fixe was er findet, retry. Wenn auch nach 3 Retries rot: dieser EINE Commit bleibt lokal, ALLE anderen pushst du trotzdem, Notiz im Final-Handoff.
  • Wenn Coolify-Deploy hängt: 10 min warten (mit until-loop oder Monitor-Tool), dann in PROGRESS dokumentieren und weitermachen mit der Verifikations-Sektion was geht.
  • Wenn Browser-Smoke rot wird: Screenshot ablegen, in PROGRESS verlinken, KEINEN Rollback machen.
  • Wenn der Token unter ~/.cli-tokens/coolify-token nicht funktioniert: API direkt via ssh control "..." ansprechen geht nicht (Coolify-API ist nur extern), dann eben curl-Sequence mit voller URL + bearer manuell, der Token-Inhalt steht in der Datei.

Was du NIE machst:

  • Rückfragen an den User (er schläft).
  • git reset --hard oder git push --force ohne dass es absolut zwingend ist.
  • Production-Touches (es gibt eh keine prod-VM aktuell, aber falls eine auftaucht: Hände weg).
  • Restore von Backups (das ist Operator-Pfad).
  • Sentry-Volumes löschen (Rollback-Optionalität schützen).

6. Operator-Profil

  • B2B-SaaS, SEO irrelevant.
  • Antwortstil im Final-Handoff: kurz, plain, keine Tabellen-Wände, keine Emojis. Pfade/URLs/Env-Vars als Fließtext, nicht inline-code.

Ende. Lies das Dokument zu Ende, dann mache deinen TaskCreate-Aufruf für Task A bis G, markiere Task A als in_progress, und SOFORT loslegen.