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.mdand 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:
- Dieses Dokument komplett bis zum Ende.
HANDOFF-2026-05-24.mdfür den davor liegenden archivierten Stand (Bucket-1-Abbau, zentrale Observability-Infra)..claude/CLAUDE.md— React-Router-v7-Konventionen sind hart enforced.- Wenn du Infra anfasst:
toolctrl-labs/infraauf 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 (PKid,TenantSettingsRowcursortenantId).packages/cli/src/commands/tenant/json-codec.ts— JSON-Replacer für Date/BigInt/Buffer/Decimal (überthis[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 Keystitle/descriptionstattsubject/message;fromEmail+fromUrlwaren ungemappt.Event-Map referenziertepayloadstatt des realen Feldesdata.
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-stagingrunter, RAM 24Gi → 4.6Gi. - Marketing-VM im Mesh als
10.42.0.5,up=1beide Jobs, infra-Repo Commit66f1357schon gepusht. - 63 Coolify-Env-Duplikate weg, kein Redeploy ausgelöst.
- Coolify-Token liegt unter
~/.cli-tokens/coolify-token, API aufhttp://195.201.133.26:8000/api/v1.
2. Historical Arbeitsplan — superseded
2.1 Goldene Regeln (jede einzelne ist nicht verhandelbar)
- 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.
- 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_progressbevor du anfängst,completedwenn du fertig bist. Lass die Liste durchgängig aktuell — sie ist deine eigene Spur. - NUTZE SUBAGENTS aggressiv. Pro Task ist ein Subagent-Vorschlag in 2.2 angegeben. Wenn du
Planbrauchst weil unklar — spawnPlan. Wenn du parallel arbeiten kannst — spawn mehreregeneral-purposein einem Tool-Use-Block. Wenn du suchst — spawnExplorestatt selbst zu greppen. Subagents geben dir Zusammenfassungen ohne deinen Kontext zu fluten. - 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.
- 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.
- 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.
- NIEMALS
git add -A— explizite Paths.packages/db/generated/**NIEMALS mitcommitten. - Kein UI-Design-Urteil treffen. Wenn ein Task „wie soll das aussehen?" verlangt: vorhandene UI-Primitives aus
packages/uirecyclen, nichts Neues erfinden. Banner-Texte, Button-Labels — nimm das Offensichtliche (englisch oder das was die Codebase vorhandene Strings hat). - Tests müssen grün bleiben.
pnpm test+pnpm typecheckmüssen vor jedem Commit grün sein. Lefthook erzwingt typecheck pre-push. - 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.
Task A — #20 Magic-Link-Invitation: User.passwordHash nullable
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:
- Prisma-Migration
User.passwordHash String?(nullable). Existierende Hashes NICHT touchen. - Auth-Boundary: Login mit null passwordHash → Magic-Link-Flow statt 401.
- Invitation-Flow: neuer User ohne passwordHash, sofort Magic-Link statt Passwort-Setzen-Email.
- 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:
- 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. - Dismissible + „Remind me in 7 days"-Pattern aus Detail-MD.
- Server-side: welche User-IDs „policy-non-compliant" sind (Funktion vermutlich da).
- 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:
- Bei Redis-Reconnect: lokale Cache-Einträge die zwischen Disconnect und Reconnect entstanden sein könnten flushen (oder invalidate-all auf Subscription-Channel-Topic).
- Integrationstest mit
testcontainers(Redis im Container starten, Verbindung killen, neue starten, asserten dass stale Reads weg sind). - Opt-in-Pattern wie
packages/db/src/outbox-claim.test.ts(envPUBSUB_TEST_REDIS_URLo.ä.). 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:
- Call-Site-Migrationen: jeden Outbox-Producer aus der Detail-MD auf
outboxDispatchumstellen. - CLI
toolctrl-cli outbox requeue --event-id=Xundoutbox requeue --type=Y --since=Z. - 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:
- Per-Modul Coverage-Gates aktivieren (vitest config in jedem Paket).
- Kritische-Pfad-Module auf 85-95% hochziehen — Liste in Detail-MD.
- 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:
lost-pixelals CI-Step gegen Storybook-Builds.- Toolbar-Globals (i18n-Locale-Switch, Theme-Switch) als Decorators.
- Tailwind-v4-Pipeline für Storybook sauber.
- 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:
- Beim Snapshot referenzierte
User-Rows (+ andere globals nach Bedarf) mitextrahieren. Neuer Top-Level-Manifest-Eintragglobals/User.jsonl(cleaner als ins existierende Schema integrieren). - Restore: globals ZUERST replayen (FK-Reihenfolge), dann tenant-scoped.
- Anonymizer-Coverage für neue globale Felder (User hat
email,firstName,lastName,phone, etc. — alle anonymisieren). - Round-Trip-Integration-Test erweitern: Restore in WIRKLICH leere DB muss jetzt grün sein für alle 12 Models.
- 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):
Planfür Architektur-Fragen,Explorefür Codebase-Suchen,general-purposefü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-testswenn 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:
- Login-Page lädt:
curl -sI https://boiler.saas-ctrl.com/login | head -3→ HTTP 200. - 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.:Run: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();SMOKE_EMAIL=... SMOKE_PASSWORD=... pnpm tsx /tmp/smoke.ts - Healthcheck-Endpoint falls vorhanden:
curl -s https://boiler.saas-ctrl.com/api/healthz(oder/health— selbst finden). - 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-tokennicht funktioniert: API direkt viassh 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 --hardodergit push --forceohne 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.