Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,158 @@
# Staging-Access
**Status:** Historical staging inventory, last refreshed 2026-05-25. Use this
file as context only; current agent instructions, `docs/agent-entrypoints.md`,
and `docs/ops/worker-queues.md` take precedence for active work.
The operator checklist, blockers page, and deployment runbooks are the
readiness-authoritative sources for B-008/B-012 and worker/Coolify state; this
archive may preserve old hotfix context that should not be copied into new
runbooks without re-verification.
Do not paste secrets, token values, or one-off credential commands into this
file. Keep private access material in the local operator token store or a
non-versioned runbook, and document only the sanitized resource shape here.
Server-Daten plus Live-Recon-Ergebnisse. Agenten arbeiten staging-abhängige Tasks (Phase 02 Sentry, Phase 03 Redis/PgBouncer, Phase 09 Authentik, etc.) gegen diesen Host.
## Hetzner-Server
- **Host / IP:** `46.225.5.93` (reverse DNS `static.93.5.225.46.clients.your-server.de`)
- **Hetzner ID:** `130197583`
- **Hostname:** `boilerplate-staging`
- **Location:** `nbg1` / Nürnberg
- **OS:** Ubuntu 24.04.3 LTS (Noble), kernel 6.8
- **Hardware:** 16 vCPU, 30 GiB RAM, 75 GB disk (12 % used after Sentry-stack deploy 2026-05-17)
- **SSH-User:** `root`
- **SSH-Port:** 22
- **SSH-Key:** Hetzner key `macbook-raffael`. Lokal als `~/.ssh/node1` hinterlegt, über `~/.ssh/config` Host-Alias `boilerplate-staging` gemappt → Connect mit `ssh boilerplate-staging`.
- **Sudo:** root direkt, keine Einschränkung.
- **Firewall:** UFW inaktiv → relies on Hetzner Cloud Firewall (rules separat checken). Offene Host-Ports: 22, 80, 443, 8080 (Traefik-Dashboard — Operator: ggf. einschränken).
## CI / Gitea-Actions Runner (entdeckt 2026-05-18)
- **Runner-Host:** `homeserver` (`~/.ssh/config` alias → `192.168.178.62`, LAN-only — also kein Hetzner-Cloud-Host).
- **Runner-Container:** `gitea-runner` (image `gitea/act_runner:latest`, version v0.6.1, "Up 8 days").
- **Runner-Name (Gitea-side):** `toolctrl-runner-01` — das ist das Label, gegen das die Workflow-Direktive `runs-on: toolctrl-ci` matcht.
- **Co-located mit:** Gitea selbst (`gitea` + `gitea-db` Container auf derselben Maschine `homeserver`).
- **Logs einsehen:** `ssh homeserver "docker logs --tail 200 gitea-runner"` für Runner-Heartbeat / Task-Pickup-Pattern. Einzelne Task-Logs liegen unter `/data/gitea/actions_log/<owner>/<repo>/<bucket>/<task_id>.log.zst` im Gitea-Container; per `docker exec gitea cat … | zstd -d` decodierbar — oder simpler via Gitea-UI.
- **Action-Runs in Gitea-DB:** `docker exec gitea-db psql -U gitea gitea -c "SELECT id, title, status, commit_sha FROM action_run WHERE repo_id=(SELECT id FROM repository WHERE owner_name='toolctrl-labs' AND lower_name='boilerplate') ORDER BY id DESC LIMIT 10"`. Status-Codes: `1=success`, `2=failure`, `3=cancelled`, `4=skipped/blocked`, `5=blocked`, `6=running`, `7=waiting`.
- **Workflow-Dispatch manuell:** use Gitea's workflow-dispatch API with a
repository-write token from the private operator token store. Do not commit
token file names or token-specific shell snippets here. HTTP 204 means the
run was enqueued.
- **Bekannte Failure-Mode (B-012):** Docker `default-address-pool` läuft auf dem Runner-Host voll (Default = 31 × `/20` aus `172.17.0.0/12`). Symptom: jeder Job failt sofort beim Setup-Step mit `Error response from daemon: all predefined address pools have been fully subnetted`. `deploy-preflight` wird rot, `stage-or-promote` skipped → CI sieht aus "läuft", aber baut nichts mehr. **Hotfix:** `ssh homeserver "docker network prune -f"` (entfernt orphaned `GITEA-ACTIONS-TASK-*-network`-Einträge aus früheren Crashes; safe weil keine Container mehr dran hängen). **Long-term:** `/etc/docker/daemon.json` auf größeres Default-Pool umstellen (z.B. `{"default-address-pools":[{"base":"10.200.0.0/16","size":"24"}]}`) plus Daemon-Restart → ~256 Subnets statt 31. Ist als operator-Item offen (s. B-012).
## Coolify
- **Rolle dieses Hosts:** Coolify-managed **Target** (kein Controller!). Coolify-Dashboard läuft auf einem separaten Host.
- **Controller-URL:** `https://saas-ctrl.com` (verified 2026-05-18 via `coolify-sentinel` PUSH_ENDPOINT env — `/api/v1/teams` mit Bearer-Token aus `~/.cli-tokens/coolify-token` → 200 OK).
- **Controller-Host:** Hetzner-VM `control` (Hetzner-Project `devops`, IP `195.201.133.26`, SSH-Alias `control`). Container-Set: `coolify` (App), `coolify-db` (postgres:15), `coolify-redis`, `coolify-realtime`, `coolify-proxy` (Traefik v3.6), `coolify-sentinel`.
- **Coolify-Agent auf diesem Host (= 46.225.5.93):** `coolify-sentinel` v0.0.21 + `coolify-proxy` (Traefik v3.6) als laufende Container.
- **Coolify-Project:** `boilerplate`
- **Coolify-Environment:** `validation`
- **Coolify-App-Ressourcen (live state refreshed 2026-05-25):**
- `boilerplate-web` → `mrf8lj70kmy9hqprx9dd6w7q` (fqdn: boiler.saas-ctrl.com + www + admin)
- `boilerplate-api` → `e109dzc3xzjxi54llfje4tob` (fqdn: api.boiler.saas-ctrl.com)
- `boilerplate-worker` → `k6cibn0rkrrl7izw970ao1l4` (legacy env-source app; no active single-worker container expected)
- Persistent worker-group apps: `worker-general`, `worker-mail`, `worker-import`, `worker-webhook`, `worker-plugin` (same worker image, separate `WORKER_QUEUE_GROUP` values, no public fqdn)
- **Deploy-Trigger:** Auto-Deploy per Image-Tag (= full git SHA). Push auf `main` → Gitea-CI baut → Coolify pullt das neue Tag → Container-Replace.
- **Container-Registry:** `git.tool-ctrl.de/toolctrl-labs/boilerplate/{web,api,worker}`.
- **Worker topology:** five separate worker containers verified healthy on staging with group-specific health ports `9101`-`9105` and admin ports `9201`-`9205`. `worker-mail` is the permanent `WORKER_QUEUE_GROUP=mail` service that drains `toolctrl.email`; `worker-plugin` owns `toolctrl.plugin-invoke`. See `docs/ops/worker-queues.md`.
- **Branch-Konvention:** Coolify trackt aktuell `main`. **Operator-Bestätigung nötig:** wir arbeiten jetzt direkt auf `main` → jeder Commit deployt nach Staging. Falls das nicht gewünscht ist, einen separaten `staging`-Branch einführen oder Auto-Deploy in Coolify pausieren.
## Reverse-Proxy / TLS
- **Proxy:** Traefik v3.6 via `coolify-proxy`-Container.
- **TLS:** Let's Encrypt ACME — Cert-Store `/data/coolify/proxy/acme.json`.
- **Traefik-Dashboard:** Port `8080` auf 0.0.0.0 — ⚠ Operator-Hinweis: per Cloud-Firewall einschränken oder Basic-Auth davor.
## Public Hostnames
Aktuell aktive Subdomains (per Traefik-Label am Container-Set verifiziert):
| Service | URL |
|---|---|
| Web (Tenant-App) | https://boiler.saas-ctrl.com |
| Web (www-Alias) | https://www.boiler.saas-ctrl.com |
| Admin-Panel | https://admin.boiler.saas-ctrl.com |
| API | https://api.boiler.saas-ctrl.com |
| Worker | — (kein public route) |
⚠ Plan-Doku spricht stellenweise von `*.toolctrl.de`. Aktuell zeigt KEIN `toolctrl.de`-Subdomain auf 46.225.5.93. Operator entscheidet ob (a) zusätzliche `*.toolctrl.de`-DNS auf den Host gesetzt werden oder (b) `saas-ctrl.com` der offizielle Staging-Hostname bleibt und Plan-Doku angepasst wird.
## Datenbank (Postgres, staging)
- **Container:** `rs3pdxczfhmxuqyx3k0uy2co` (pgvector/pgvector:pg16 — swapped 2026-05-18, pgvector 0.8.2 installed; previously postgres:16-alpine, see B-010 in BLOCKERS.md)
- **Network:** nur auf Docker-Network `coolify` (kein Host-Port 5432)
- **DB-Name:** `boilerplate_validation`
- **User:** `boilerplate`
- **Connection-String-Template:** `postgres://boilerplate:${PG_PASS}@rs3pdxczfhmxuqyx3k0uy2co:5432/boilerplate_validation`
- **Passwort:** in Coolify-Env hinterlegt. Resolve ad hoc through the private
operator process when needed, but do not paste live connection strings into
repository documentation.
- **Migrations-Berechtigung:** Agent darf Prisma-Migrations laufen lassen. **Bestätigung gewünscht:** vor jeder Schema-Migration `pg_dump` snapshot anlegen (oder Coolify-Volume-Backup vorher).
## Redis (staging)
- **Container:** `bcub98rmhlr1ouufprihgvad` (redis:7-alpine)
- **Network:** nur intern auf `coolify`
- **User:** `default`
- **Passwort:** in Coolify-Env hinterlegt; bei Bedarf über den privaten
Operator-Prozess oder die Coolify-Umgebung auflösen, aber nicht in
Repo-Dokumentation eintragen.
- **URL-Template:** `redis://default:${REDIS_PASS}@bcub98rmhlr1ouufprihgvad:6379`
- **FLUSHDB:** erlaubt für Tests (keine Production-Daten auf staging)
## Externe Services — aktueller Stand
| Service | Status auf staging | Phase-Bezug |
|---|---|---|
| Sentry-Self-Hosted | **installiert** auf `/opt/sentry-stack/` (NICHT Coolify-managed), Traefik-routed via `https://sentry.boiler.saas-ctrl.com` (Let's Encrypt), 3 Projects: `boilerplate-api` (id=2), `boilerplate-worker` (id=3), `boilerplate-web` (id=4) — DSNs in `~/.cli-tokens/boilerplate-staging-env`. 2026-05-18: postgres + pgbouncer subcontainers restarted (had been crashlooping since 2026-05-17 disk-full); `SENTRY_AUTH_TOKEN` minted via Django ORM in `sentry-self-hosted-web-1` (`~/.cli-tokens/sentry-auth-token-staging`, scope: project:releases+read, org:read, project:write, member:read), pushed to Coolify-Env on all 3 apps (build-time on web) + Gitea-Actions secret on `toolctrl-labs/boilerplate`. | Phase 02 #29 — auth-token live 2026-05-18 |
| Authentik | **installiert** auf `/opt/authentik/` (NICHT Coolify-managed), Traefik-routed via `https://auth.boiler.saas-ctrl.com` (Let's Encrypt), 4 Container (server/worker/postgresql:16/redis:7) auf `authentik-net` + `coolify`-Network. Secrets in `~/.cli-tokens/authentik-staging-env`. Bootstrap-Login `admin@tool-ctrl.de` + `AUTHENTIK_BOOTSTRAP_PASSWORD`. 2026-05-18: alle 3 toolctrl-Blueprints `status=successful`; OIDC-Discovery-Endpoint live. **Admin-OIDC provider 2026-05-18 via API auf real `client_id=toolctrl-admin-panel` + 64-hex client_secret + redirect_uri `https://boiler.saas-ctrl.com/auth/admin/callback` rotiert** (creds in `~/.cli-tokens/authentik-oidc-staging`). Web-App Coolify-Env `OIDC_AUTHENTIK_{ISSUER,CLIENT_ID,CLIENT_SECRET,REDIRECT_URI}` gesetzt — **CORRECTION 2026-05-19:** das war der falsche Namespace. Der Code (`apps/web/app/modules/admin-sso/client.server.ts:38-49`) liest `AUTHENTIK_ISSUER_URL` + `AUTHENTIK_ADMIN_CLIENT_ID` + `AUTHENTIK_ADMIN_CLIENT_SECRET` + `AUTHENTIK_ADMIN_REDIRECT_URI`. Solange die alten Namen gesetzt waren, redirected `/auth/admin/login` mit `error=sso_unavailable`. Korrigiert via Coolify-API-POST (4 neue korrekt benannte Envs) + DELETE der 8 dead `OIDC_AUTHENTIK_*` Einträge (4 prod + 4 preview) + Web-Redeploy. Smoke: `/auth/admin/login` 302t jetzt zu Authentik's `/application/o/authorize` mit vollem PKCE-Setup. | Phase 09 #81/#82 — OIDC chain live 2026-05-19 (E2E login flow requires user creds, not testable from automation) |
| PgBouncer | **installiert** auf `/opt/pgbouncer/` (NICHT Coolify-managed), `edoburu/pgbouncer:latest`, attached to `coolify`-Network, internal hostname `boilerplate-pgbouncer:6432`, pool_mode=transaction, default_pool_size=25. `userlist.txt` SCRAM-SHA-256 hash für `boilerplate`-User direkt aus `pg_authid` kopiert. **App-DATABASE_URL-Flip done 2026-05-18 via Coolify-API** auf web/api/worker (`DIRECT_URL` points to raw postgres for migrations; `DATABASE_URL` routes via pgbouncer). 2026-05-19: Healthcheck-Drift gefixt — staging `/opt/pgbouncer/docker-compose.yml` hatte `nc -z localhost 6432` (BusyBox `nc` löst `localhost` zu `::1` IPv6 auf, pgbouncer bindet aber nur IPv4 via `listen_addr = 0.0.0.0` → 10786 healthcheck-Fails). Auf den canonical Repo-Pattern `pg_isready -h 127.0.0.1 -p 6432 -U pgb_admin` umgestellt + `docker compose up -d --force-recreate`. Container jetzt `(healthy)`. Backup unter `/opt/pgbouncer/docker-compose.yml.bak-20260519-071532`. | Phase 03 #40 — env flipped 2026-05-18, healthcheck-drift fixed 2026-05-19 |
| Prometheus | **installiert** auf `/opt/observability/prometheus/`, `prom/prometheus:v3.6.0`, eigenes Docker-Network `boilerplate-observability` + `coolify`. METRICS_TOKEN bind-mounted nach `/etc/prometheus/secrets/metrics_token`. 2026-05-18: METRICS_TOKEN auf staging rotiert (`~/.cli-tokens/metrics-token-staging`), Prometheus SIGHUP'd; App-Env `METRICS_ENABLED=true` + `METRICS_TOKEN=<same>` auf web/api/worker via Coolify-API gesetzt. | Phase 02 #35 — env flipped 2026-05-18 |
| Grafana | **installiert** auf `/opt/observability/grafana/`, `grafana/grafana-oss:11.4.0`, public via `https://grafana.boiler.saas-ctrl.com` (Let's Encrypt). Admin-Pass + Prometheus-Token in `~/.cli-tokens/grafana-staging-env`. 5 Dashboards provisioned (overview, api-latency, ai-cost-per-tenant, business-kpi, queue-health). | Phase 02 #35 — staging-deploy am 2026-05-18 done |
| ClamAV | **installiert** auf `/opt/clamav/`, `clamav/clamav:1.0`, attached to `coolify`-Network, internal hostname `boilerplate-clamav:3310`, named volume `boilerplate-clamav-sigdb` (3.64M sigs). EICAR smoke green. **App-Env-Flip (`CLAMAV_HOST`, `CLAMAV_PORT`, `AV_LAYER_2_ENABLED`) done 2026-05-18 via Coolify-API** auf web/api/worker. `FileObject` scan-columns-migration pending. | Phase 01 #17 — env flipped 2026-05-18 |
| Meilisearch | **installiert** auf `/opt/meilisearch/` (NICHT Coolify-managed), `getmeili/meilisearch:v1.8`, attached to `coolify`-Network only (no Traefik route — internal-only), container name `boilerplate-meilisearch`, internal port 7700, named volume `meilisearch-data`, `MEILI_ENV=production`, `MEILI_MASTER_KEY` (64-hex) in `~/.cli-tokens/meilisearch-staging-env`. Health-smoke `{"status":"available"}` green; `/version` → 1.8.4 with master-key auth. **App-Env-Flip (`MEILI_URL=http://boilerplate-meilisearch:7700`, `MEILI_MASTER_KEY=<same>`) done 2026-05-18 via Coolify-API** auf web/api/worker. 2026-05-19: Healthcheck-Drift gefixt (gleicher IPv6-Issue wie pgbouncer) — `/opt/meilisearch/docker-compose.yml` Test war `wget http://localhost:7700/health` aber BusyBox-`wget` löste `localhost` zu `::1` IPv6, Meilisearch bindet IPv4-only → 3646 Health-Fails. Auf `http://127.0.0.1:7700/health` umgestellt + `docker compose up -d --force-recreate`. Container jetzt `(healthy)`. Backup unter `/opt/meilisearch/docker-compose.yml.bak-…`. | Phase 04 #48 — env flipped 2026-05-18, healthcheck-drift fixed 2026-05-19 |
| S3 / MinIO | **nicht installiert** | Phase 01 #18 expected S3-Backend — derzeit nutzt die Boilerplate-Instanz lokalen Filesystem-Storage oder gar nichts (per Recon nicht eindeutig — Coolify-Env-Dump prüfen) |
| Email-Provider | MailerSend configured for staging mail delivery; persistent `worker-mail` drains `toolctrl.email` | Phase 10 #75 React-Email / Phase 01 #19 |
## Agent-Workflow auf diesem Host
> **Archived superseded notes:** this section records how agents worked against
> staging in May 2026. It is not standing permission to pull, push, deploy,
> flush Redis, or run migrations. Follow the current conversation, repository
> instructions, and active runbooks before touching live services.
- **Branching:** Historical note only. Follow the current conversation and
repository instructions for branch, commit, push, and deploy behavior. Do not
treat this file as standing permission to push or deploy.
- **Paralleler zweiter Agent:** Ein anderer Agent arbeitet ebenfalls am Repo. Bei jedem Workflow-Anfang `git pull --rebase` ausführen, vor jedem Push erneut, bei Konflikten manuell mergen.
- **DB-Migrationen:** Per `docker exec` in den web-Container, `pnpm --filter @toolctrl/db prisma migrate deploy`. Vorher Backup-Empfehlung (`pg_dump`).
- **Worker-Queue-Reset für Tests:** `docker exec -it <redis-container> redis-cli -a <pass> FLUSHDB`.
## DNS / TLS-Operations
- **Wildcard-Subdomain:** keine konfiguriert — Coolify legt pro App-Hostname einen eigenen Traefik-Cert an.
- **Neue Hostnames:** zusätzliche DNS-A-Records auf `46.225.5.93` zeigen lassen, dann in Coolify als zusätzliche Domain am betreffenden App-Container hinterlegen → Traefik kümmert sich um Cert automatisch (Let's Encrypt HTTP-01).
## Operator-Notification-Channel
- Standard: `docs/improvement-plan/ASK-OPERATOR.md` für blocker-mäßige Fragen, `BLOCKERS.md` für hartes Warten.
- Slack/Discord-Webhook: ❌ keiner konfiguriert.
## Offene Operator-Items
> **Archived superseded notes:** these were the open items when this inventory
> was last refreshed. Check current active operator docs before treating any
> item below as still open.
1. **Coolify-Dashboard-URL** + Login-Methode (für UI-basierte App-Management-Aufgaben).
2. **`*.toolctrl.de` vs `*.saas-ctrl.com`** — eines auswählen und Plan-Doku synchronisieren.
3. **Traefik-Port 8080** firewallen oder Auth davorhängen.
4. **MinIO / S3-compatible object storage** provisionieren, falls Phase 01 #18 oder Upload-Flows nicht beim lokalen Filesystem bleiben sollen. Sentry, Authentik, ClamAV, PgBouncer, Meilisearch, Prometheus und Grafana laufen bereits als staging services, aber teilweise bewusst außerhalb von Coolify.
5. **Pre-Migration-Backup-Hook**: möchten wir vor jedem Schema-Deploy ein Snapshot? (Coolify hat keinen Built-In, müsste als pre-deploy-Hook ergänzt werden.)
---
_Wenn diese Datei nach einer Änderung wieder veraltet wirkt: einfach `ssh boilerplate-staging 'docker ps; ss -tlnp; df -h /'` laufen lassen und Sektionen aktualisieren._
@@ -0,0 +1,238 @@
# Handoff — Stand 2026-05-20
> **Historical snapshot only (2026-05-25 cleanup).** This file is preserved
> for audit/history. Do not treat its "start", "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:** Phase 06 Plugin-System — von "audit-package zusammenstellen" bis "fast alle internen Findings remediated"
**Ziel des Handoffs:** Nachfolge-Agent soll in **3 Minuten** wissen wo wir stehen, was gerade kein Code-Problem sondern Operator-Arbeit ist, und welche Tracks Code-Arbeit brauchen.
---
## 1. Was die letzte Session bewegt hat (29 commits auf `main`)
Phase 06 (Plugin-System) #23 von `pending` → `in_progress (operator-audit-pending)`. Audit-Package-Layer + 12 interne Findings remediated mit Tests.
Schlüssel-Artefakte:
- `docs/security/plugin-threat-model.md` — 14 Assets × STRIDE, jede Mitigation per `file:line` an Code gehängt
- `docs/security/plugin-attack-surface.md` — 9 Capabilities, Manifest-Felder, DB-Tabellen, Routes, Env
- `docs/security/plugin-internal-findings.md` — 24 F-NNN Findings, 23 davon disposed (closed / accepted-residual / blocked-on-precondition / blocked-architecturally)
- `docs/security/plugin-audit-rfp.md` — RFP mit Vendor-Empfehlung Cure53 (Alternates: Trail of Bits / NCC Group / SySS / secfault), 25k EUR Cap
- `docs/security/plugin-runtime-signoff.md` — Joint Sign-Off-Template
- `scripts/build-plugin-audit-package.sh` — bündelt In-Scope-Code + Docs + SHA-256-Manifest in ein tar.gz (smoke-getestet ~209 KB)
- `docs/improvement-plan/06-plugin-system/security-findings/README.md` — Folder-Convention für künftige Findings-Files
Code-Remediations diese Session (alle mit Tests + grünem Lefthook-Pre-Commit):
- F-015 Critical (worker bootstrap unwired) — `handlePluginInvokeJob` jetzt wirklich an BullMQ angeschlossen
- F-005 Phase A + B — Install-Path Trust-Store-Gate + binary-on-disk verify
- F-017 — Manifest-Schema um `minHostVersion`/`maxHostVersion` erweitert
- F-010 — CSRF-body-consumption immunity verifiziert
- F-014 — sanitize total-size budget
- F-011 — install-route per-tenant rate limit
- F-008/F-009/F-021/F-023 — Medium-Sweep (statement cap, install cap, tenantId regex, circular-ref WeakSet)
- F-007/F-020 — per-stmt migration audit + audit-table-size warning
- F-006 — Token-aware migration scan (ersetzt substring-only Forbidden-Token-Check)
- F-003 — `PluginCapabilityUse` per-tenant hash chain (Prisma migration + verifier)
- F-001 backend — `TenantPluginCapabilityGrant` Modell + enable-time consent-gate (UI deferred)
- F-013/F-016/F-018/F-019/F-012 — als accepted-residual / documented / blocked-on-precondition geschlossen
Nur **F-002** bleibt offen — per-instruction fuel braucht Wasmtime-Swap (multi-week, architektur). Konkrete Two-Track-Remediation steht in der Findings-Datei.
---
## 2. Gesamt-Projekt-Status
```
Total Tasks: 63 aktiv + 7 Backlog
Completed: 35 / 63 (56%)
In Progress: 28 / 63
Pending: 0
Backlog: 7
Blocked-hart: 0 (siehe BLOCKERS.md für Operator-Anfragen)
```
Die "In Progress: 28" zerfallen in drei sehr unterschiedliche Buckets — das ist das wichtigste was der nächste Agent verstehen muss.
### Bucket A — Operator-Pending (~14 Tasks, KEINE Code-Arbeit)
Code ist fertig + getestet, was fehlt ist eine Operator-Aktion (env flip, deploy, account setup, store submission, live E2E test). **Nicht anpacken ohne klaren Operator-Auftrag.**
| Task | Operator-Aktion |
| --------------------------------- | ------------------------------------------------------------------------ |
| #16 / #17 AV-Layer 1+2 | Erste echte EICAR-Upload-Smoke auf staging |
| #19 / #20 Magic-Link / Invitation | Live E2E-Flow auf staging |
| #23 Phase 06 #23 | **External pen-test dispatch** (B-006) — siehe Section 4 |
| #26 TOTP | Live MFA enroll/challenge E2E |
| #29 / #30 / #32 Sentry | Workflow-Smoke + Project-Setup |
| #40 PgBouncer | App `DATABASE_URL` flip |
| #41 R/W-Split | Replica deploy + connection-string flip |
| #51 Asset-CDN | CDN-Zone provisionieren |
| #56 AI-Cost Phase 3 | Stripe-Account Meter-Setup (siehe `docs/ops/stripe-meters-migration.md`) |
| #65 Mobile | Native-builds + App Store / Play Store submission |
| #27 Password-Policy | Login-Soft-Banner (Code-Stub existiert, UI-Polish deferred) |
### Bucket B — Code-Sprint-Deferred (~13 Tasks, ECHTE Code-Arbeit)
Foundation ist da, Feature-Vervollständigung steht aus. Diese sind die echten "weitermachen"-Kandidaten.
| Task | Was zu tun ist | Aufwand |
| ------------------------------ | --------------------------------------------------------------------------------------------------------- | ---------- |
| **#21 / #22 Plugin Phase 1+2** | Hot-reload, marketplace, sandboxed iframe, output-hooks, 13 zusätzliche hook-points, global crash counter | 2-3 Wochen |
| **#38 Shared-Store** | 3 von 6 Stores migriert; idempotency + subscription-cache + session offen | 1 Woche |
| **#42 Outbox** | Foundation shipped; call-site migrations, admin UI, CLI re-queue, e2e tests offen | 1 Woche |
| **#39 Pub/Sub** | feature-flag invalidation in Phase 05 wired-up | 2-3 Tage |
| **#53 Feature-Flags** | Visual rule builder UI | 3-5 Tage |
| **#55 AI-Cost Quota** | Admin + tenant UI + CLI | 3-5 Tage |
| **#59 Realtime-Collab** | Andere Editoren als Novel anbinden (Hocuspocus) | 1 Woche |
| **#62 Storybook** | a11y / visual-regression / test-runner | 3-5 Tage |
| **#72 i18n** | 200+ jsx-text + prop-literal extractions (`/72 i18n migration sprint` in D1) | 3-5 Tage |
| **#73 WCAG** | Axe-violation Backlog abarbeiten | 5-7 Tage |
| **#76 Test-Coverage** | Per-Module-Gates ratchet | 5-10 Tage |
| **#78 Marketing-Funnel** | Admin-Sidebar wiring + Turnstile staging-verify | 1-2 Tage |
| **F-002 (Phase 06)** | Per-instruction fuel via Wasmtime-Swap ODER worker-thread + wall-clock kill | multi-week |
### Bucket C — Backlog (7 Tasks, on-demand)
#24 (Marketplace), #52, #57, #64, #66, #74, #77 — explizit "nur wenn jemand fragt", nicht auf der aktiven Roadmap.
---
## 3. Offene Operator-Blocker (BLOCKERS.md)
> **Superseded blocker status (2026-05-28):** this section is preserved as
> the 2026-05-20 snapshot. Current truth: B-006 remains the external plugin
> production gate; B-008 is closed by operator disk-pressure alerting; B-012
> is a mitigated runner-host recurrence risk, not an active deploy/code
> blocker. Use `../../OPERATOR-CHECKLIST.md` and `../../BLOCKERS.md`.
### Aktuell **open**:
- **B-006 — External Security Review of WASM Sandbox** (Phase 06 production rollout gate)
- Audit-Package + RFP + Vendor-Memo + Sign-Off-Template alle ready (siehe Section 4)
- Operator: Cure53 (oder einer der 4 Alternates) engagieren, 3-5 Tage Pen-Test, ~15-25k EUR
- **B-008 — Disk-pressure monitoring** (Aftermath: containers wieder up, prevention pending)
- Operator: Grafana-Alert + automated `docker system prune` cron
- **B-012 — Gitea-runner Docker default-address-pool** (mitigated 2026-05-18, permanent fix operator-owed)
- Operator: `/etc/docker/daemon.json` auf `homeserver` editieren + dockerd restart
### Resolved (siehe BLOCKERS.md für Archiv):
B-001 (Stripe 13→19), B-002 (Staging-Access), B-003 (Push-Strategie), B-005 (Sentry OTLP), B-007 (Authentik blueprints), B-009 (Lighthouse session-cookie), B-010 (pgvector + migrations), B-011 (Worker Dockerfile), B-013 (Vite node:crypto)
---
## 4. Phase 06 — Production-Rollout-Path (konkrete Schritte)
> **Archived superseded notes:** this rollout path predates later plugin
> readiness and worker-topology docs. Use `docs/operations/plugin-lifecycle.md`,
> `docs/worker.md`, `docs/ops/worker-queues.md`, and
> `docs/security/plugin-runtime-signoff.md` for current runtime gates. In
> particular, the production gate is now `PLUGIN_RUNTIME_PRODUCTION_ENABLED`,
> not the older `PLUGIN_RUNTIME_ENABLED` wording below.
Phase 06 ist der einzige Track der gerade "audit-ready" ist und auf eine externe Operator-Aktion wartet. Der Pfad zur completed-Markierung:
1. **`git push`** — die 29 lokalen commits auf `main` müssen nach `origin` (Pre-Push-Hook ist grün seit `3afbb257`)
2. **`bash scripts/build-plugin-audit-package.sh`** — erzeugt `artifacts/plugin-audit/2026-05-20/plugin-audit-<sha>.tar.gz`
3. **RFP + Archive an Cure53 verschicken** per `docs/security/plugin-audit-rfp.md` § 9 (E-Mail-Template am Ende der RFP-Datei)
4. **Während des Audits (~3 Wochen):** Findings werden unter `docs/improvement-plan/06-plugin-system/security-findings/F-NNN-….md` abgelegt. Pro Critical/High einen eigenen File mit Reproduction + Remediation-Plan.
5. **Fixes pushen → Re-Test anfragen** (Cure53 macht typischerweise 1× Re-Test im Engagement)
6. **`docs/security/plugin-runtime-signoff.md`** ausgefüllt + von Operator + Lead Auditor signiert
7. **Production-Env-Vars setzen** _bevor_ `PLUGIN_RUNTIME_ENABLED=true`:
- `PLUGIN_TRUSTED_PUBLIC_KEYS=<CSV von hex Ed25519 keys>` (Operator-Aktion)
- `PLUGIN_INSTALL_SKIP_BINARY_VERIFY=false` (Default — NICHT auf true setzen in Prod)
- `PLUGIN_REQUIRE_CAPABILITY_CONSENT=true` (Default — NICHT auf false setzen in Prod)
- `PLUGIN_BINARY_BASE_PATH=/app/var/plugins` (oder operator-gewählt)
- `WORKER_QUEUE_GROUP=plugin` Container provisionieren (separates `worker-plugin` deploy)
8. **PROGRESS.md** Status für #23 von `in_progress (operator-audit-pending)` → `completed`
9. **F-002** bleibt nach Audit als deferred — entweder direkt im selben Rollout angegangen ODER als Phase-06-follow-up
---
## 5. Was der nächste Agent zuerst tun sollte
**Lies in dieser Reihenfolge (max 15 Minuten):**
1. Dieses Handoff-Dokument (bis hierhin)
2. `docs/improvement-plan/PROGRESS.md` Aggregat-Sektion (Zeilen 1-50)
3. `docs/improvement-plan/BLOCKERS.md` (alle `Open` Einträge)
4. `docs/improvement-plan/OPERATOR-CHECKLIST.md` § A (operator-env-flip-pending Items)
5. `docs/security/plugin-internal-findings.md` Summary-Tabelle (Section "Summary")
6. `.claude/CLAUDE.md` (React Router v7 conventions — die werden im Repo strikt enforced)
7. `AGENTS.md` im Repo-Root (Workflow + Branch-Strategie)
**Dann sprich mit dem User über die Richtung:**
> "Vorgänger hat Phase 06 audit-ready übergeben. Open Bucket-B Tracks sind A, B, C, D — welcher davon ist priorität, oder gibt es einen anderen Track der dich gerade interessiert?"
**NICHT** einfach in Phase-06-Follow-Up-Code reingehen ohne expliziten Auftrag — F-002 ist Multi-Wochen-Architektur (Wasmtime), nichts zum "kurz mal machen". Auch nicht in Bucket-A-Operator-Tracks reinarbeiten ohne klaren Anlass — der Code ist fertig, das Warten ist beabsichtigt.
---
## 6. Workflow-Konventionen (NICHT vergessen)
> **Archived superseded notes:** these workflow conventions were session-local
> for 2026-05-20. They do not override current repository instructions,
> conversation constraints, branch policy, verification scope, or commit/push
> decisions.
Aus `AGENTS.md` + Session-Erfahrung:
1. **Alle Commits direkt auf `main`** — keine Branches, Coolify deployed auto auf staging
2. **`git pull --rebase` vor Workflow-Start** — andere Agenten arbeiten parallel
3. **Lefthook Pre-Commit ist hart** — `test-density`, `eslint-baseline`, `secrets`, `lint-staged` müssen grün
4. **Lefthook Pre-Push ist hart** — full `pnpm typecheck`. Bricht den Push wenn TS-Fehler. Diese Session hatte einen Push-Fail wegen F-001 Set-Type — fix in `3afbb257`.
5. **React Router v7** — Route-Type-Imports IMMER als `./+types/<routeName>`, nie relativ. Nach Route-Add `npm run typecheck` ausführen.
6. **Niemals `git add -A`** — nur explizite Paths. Parallel-Agenten-Disziplin.
7. **Co-Author-Trailer:** `Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>`
8. **`pnpm`, nicht npm** — pnpm-workspace-Setup, `pnpm -F <pkg>` für package-scoped scripts
9. **Tests via `npx vitest run <path>`**, NICHT `pnpm test` (zu breit für TDD)
---
## 7. Push-Status (jetzt-aktuell)
> **Archived superseded notes:** the push status below is a point-in-time
> snapshot from 2026-05-20, not current repository state.
```
HEAD: 3afbb257 fix(plugins): widen capability-name Set type in F-001 grant check
local-main vs origin/main: 29 commits ahead
worktree: nur auto-generated Prisma client modifications (packages/db/generated/prisma/*)
```
**Operator sollte als allererstes `git push` durchziehen.** Die 29 Commits sind lokal, getestet, hooks-grün, aber noch nicht auf `origin`. Bis die nicht oben sind ist nichts deployed.
Wenn der Push erneut scheitert: Pre-Push-Hook Output lesen, das ist ein neuer Bug, kein bekannter Fehler.
---
## 8. Was diese Session NICHT geleistet hat (ehrlich)
- **F-002 nicht angegangen** — Wasmtime-Swap ist multi-week, nicht session-scoped. Konkrete Two-Path-Remediation in `plugin-internal-findings.md` F-002 dokumentiert.
- **Phase 06 UI** — Capability-Consent-Dialog, Sandboxed-iframe-Settings, Audit-Trail-Filter-UI sind alle deferred (#22 Deviations + F-001 backend-only)
- **13 weitere Hook-Points** — Phase 06 #22 hat 5/18 wired; 13 deferred
- **Marketplace** — Phase 11 Backlog #24, nicht aktiv
- **Andere Tracks außerhalb Phase 06** — diese Session war Phase-06-fokussiert. Bucket B (Sprint-Deferred) Items sind unverändert seit vor 2026-05-19.
---
## 9. Sofort-Sanity-Check für nächsten Agent
```bash
# Im Repo-Root
git log --oneline -5 # sollte mit 3afbb257 starten
git status -s # sollte nur Prisma-generated zeigen
pnpm -F @toolctrl/plugin-runtime test 2>&1 | tail -5 # sollte 168 tests passing
bash scripts/build-plugin-audit-package.sh # sollte tar.gz erzeugen
```
Wenn alle 4 grün: Repo ist in dem Zustand der diesem Handoff entspricht.
---
**Ende des Handoffs.** Bei Unklarheit den User fragen, nicht raten.
@@ -0,0 +1,197 @@
# Handoff — Stand 2026-05-20 (Session B)
> **Historical snapshot only (2026-05-25 cleanup).** This file is preserved
> for audit/history. Do not treat its "start", "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:** Bucket-B-Sprint — 5 Tracks bewegt + 4 Quick-Wins, ~16 commits gepusht
**Ziel des Handoffs:** Nachfolge-Agent weiß in 5 Minuten wo wir stehen und was als Nächstes dran ist.
---
## 0. Start hier (5-Minuten-Onboarding)
**Lies in dieser Reihenfolge:**
1. Dieses Dokument, Section 1c (jüngste Arbeit) + Section 3 (was offen ist) + Section 7 (Subagent-Workflow).
2. `HANDOFF-2026-05-20.md` — der ältere archivierte Handoff für Bucket-A / Operator-Kontext (historisch weiterhin relevant).
3. `.claude/CLAUDE.md` — React-Router-v7-Konventionen, strikt enforced.
4. `AGENTS.md` im Repo-Root — Workflow + Branch-Strategie.
**Sofort-Sanity-Check (Repo-Root):**
```bash
git log --oneline -3 # sollte mit 04d4dd74 (oder neuer) starten
git status -s # nur packages/db/generated/** churn erwartet
git pull --rebase # andere Agenten arbeiten ggf. parallel
```
**Dann:** einen Track aus Section 3 wählen, einen Subagenten dafür spawnen (Brief-Vorlage = wie in Section 7 beschrieben), nach Rückkehr reviewen + committen. Nicht mehrere Tracks parallel.
---
## 1. Was diese Session bewegt hat (6 commits auf `main`, gepusht)
3 Bucket-B-Tracks vollständig geschlossen + Push nach `origin/main` (`3afbb257..7c4f04e3 main -> main`, Pre-Push-Hook 42s grün).
### Track #78 — Marketing-Funnel Phase 1 → operator-staging-verify-pending
| Commit | Was |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `f4c2f908` | Admin-Sidebar: "Marketing funnel" collapsible Group im `market` segment mit Leads / Funnels / Integrations / Email sequences sub-items. Permission-gated auf `admin.marketing.*` / `admin.marketing.leads.view`. Vier neue slugs in `canonicalAdminRouteSlugs`. en/de i18n keys. Neuer `UI_NAV_IDS.adminMarketing`. |
| `89c79e9f` | Admin-UI CSV-Export: `?export=csv` branch im `marketing-leads/index.tsx` loader. 50k Row Cap. 20-column CSV byte-compatible mit `toolctrl-cli leads export`. Audit-Event `admin.marketing.leads.csv_export` mit pii/gdpr scope + Filter-Snapshot + Truncation-Flag. Download-Button im Inbox-Header. Neue `serializeLeadsCsv` + 9 unit tests. |
| `d42c06f4` | PROGRESS.md + `marketing-funnel-phase-1.md` Deviations-Sync. |
**Verbleibend für #78:** Nur Turnstile-staging-verify (Operator-Aktion, braucht live Cloudflare-Keys in staging). Kein Code-Restwork.
### Track #39 — Pub/Sub Cache-Invalidation → cross-process gap closed
| Commit | Was |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `9edc1357` | One-shot `publishFeatureFlagInvalidationOnce` Publisher in `@toolctrl/feature-flags` (öffnet SharedStore → published auf `cache:feature-flags:invalidate` → schließt Redis-Client für sauberen CLI-Exit). Neuer `broadcastFlagInvalidation` Helper in `packages/cli/src/commands/feature-flags/invalidate.ts`. CLI `toolctrl-cli feature-flags {enable,disable,set-rules}` rufen jetzt nach DB-Mutation `broadcastFlagInvalidation`. `FEATURE_FLAGS_PUBLISH_NAMESPACE` env override (default `web`). Honors `CACHE_INVALIDATION_ENABLED=false` kill-switch. 9 unit tests. |
| `459a936c` | PROGRESS.md + `pubsub-cache-invalidation.md` Deviations-Sync. Streicht das "feature-flag stub deferred" wording — was als deferred markiert war ist Phase-05 #53 längst geshipped, der einzige verbleibende Gap war der CLI-Publisher den `9edc1357` schließt. |
**Verbleibend für #39:** Nur die explizit accepted-residual Deviations (reconnect-flush wiring an Redis `ready` event, multi-process testcontainers integration test). Diese sind low-priority Follow-ups, nicht blocking.
### Track #62 — Storybook → a11y gate live
| Commit | Was |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `7c4f04e3` | `@storybook/test-runner` + `axe-playwright` Wiring in `apps/storybook/.storybook/test-runner.ts`. `postVisit` hook re-runs den WCAG-2.2-AA axe ruleset gegen jede story im headless Chromium. Per-story `parameters.a11y.disable = true` opt-outs honored mit code-comment justification. Neuer `test:storybook` npm script + `http-server`/`wait-on`/`@storybook/test-runner`/`axe-playwright` devDeps. Beide CI-Workflows (`.github/workflows/storybook.yml` + `.gitea/workflows/storybook.yml`) bekommen einen `test-storybook` job downstream des build jobs der den static artifact downloadet, http-served, Playwright Chromium installed, und PRs auf axe-violations gated. `docs/architecture/storybook.md` updated. |
**Verbleibend für #62:** Lost-Pixel visual-regression (braucht baseline screenshot generation — Operator-Schritt), brand/ui-layer toolbar globals, real Tailwind-v4 preview pipeline, Coolify static-deploy.
---
## 1b. Quick-Win-Nachschlag (4 weitere commits, gepusht — `3cec791f..6401bdbd`)
Nach dem ersten Handoff hat dieselbe Session noch 4 Quick-Wins geliefert:
| Commit | Track | Was |
| ---------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ef7c53df` | **#73 WCAG P0** | Beide P0 jsx-a11y-Violations behoben (`PaginationLink` + `StepperTitle` destrukturieren `children` explizit). Rules `anchor-has-content` + `heading-has-content` von `off` zu `error` befördert, Baseline 137→135, `wcag-audit.md` Changelog. |
| `c03560d4` | **#62 Lost-Pixel** | `lostpixel.config.ts` + `visual-regression` CI-Job (baseline-gated, self-skip bis Operator Baselines committet). Closes die Lost-Pixel-Deviation code-seitig. |
| `d4c14ab3` | **#38 Idempotency** | `createSharedStoreIdempotencyStorageClient` — Prisma-shaped Contract über SharedStore, opt-in via `IDEMPOTENCY_BACKEND=shared-store`. 12 Tests. #38 jetzt 4/6 Stores. |
| `6401bdbd` | **#55 AI-Cost CLI** | `toolctrl-cli ai-cost {show,set,reset}-quota` mit Audit-Events + 17 Tests. #55 CLI-Deviation closed; nur noch Tenant/Admin-Web-UI offen. |
---
## 1c. Subagent-Block (2 weitere commits, gepusht — `c2400950..7358eb80`)
Per Subagent abgearbeitet, jeweils orchestrator-reviewed:
| Commit | Track | Was |
| ---------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `81cfaa8b` | **#38 subscription-cache** | Subagent fand echten Cross-Replica-Bug: 5 subscription-mutierende Call-Sites (`createTenantSubscription`, `updateTenantSubscriptionCustomerId`, `addTenantSubscriptionProduct`, `updateTenantSubscriptionProduct`, `cancelTenantSubscriptionProduct` + Stripe billing-period sync) purgten nur den lokalen `cachified`-LRU via bare `clearCacheKey`, publizierten nie auf `cache:subscription:invalidate`. Nach in-app Plan-Upgrade auf Replica A sahen Peers bis zur L1-TTL veraltete Limits. Alle 5 jetzt über die publizierende `clearTenantSubscriptionCache`. 7 neue Tests. (Commit-Scope sagt fälschlich `fix(plugins)` — kosmetisch.) |
| `7358eb80` | **#73 P1 a11y** | Alle 4 P1 jsx-a11y-Rules auf 0: `label-has-associated-control` (15), `click-events-have-key-events` (13), `no-static-element-interactions` (11), `no-noninteractive-element-interactions` (2) — alle zu `error` befördert. 24 Source-Files: div→button-Konvertierungen, `htmlFor`+`id`-Label-Assoziationen, `role=button`+`tabIndex`+`onKeyDown` wo button-Konvertierung strukturell nicht ging. 5 justified `eslint-disable` (mouse-only focus-forwarding hit-areas). Baseline 135→94 (nur noch P2). |
**Track-Status nach dieser Session:**
- **#78** Marketing-Funnel — code-complete, nur Turnstile-staging-verify (Operator) offen.
- **#39** Pub/Sub — cross-process gap closed.
- **#62** Storybook — test-runner-a11y-gate + Lost-Pixel-scaffold; nur Operator-Baseline-Bootstrap + brand-toolbar-globals + Coolify-deploy offen.
- **#73** WCAG — P0 + alle P1 clear (Baseline 94, nur noch P2: `no-autofocus` 88, `anchor-is-valid` 3, `media-has-caption` 2, `no-noninteractive-tabindex` 1).
- **#38** Shared-Store — 5/6 Stores (rate-limits ×2, idempotency, subscription-cache). Nur noch Session-Store offen (höchstes Risiko — sync→async über viele Auth-Call-Sites; eigene sorgfältige Session).
- **#55** AI-Cost Quota — CLI done; Tenant+Admin-Web-UI offen.
---
## 2. Was NICHT geändert wurde (bucket-A unverändert)
> **Superseded operator snapshot (2026-05-28):** the list below records what
> was still open on 2026-05-20. Current operator truth moved to
> `../../OPERATOR-CHECKLIST.md`: B-008 is closed, A7/B2/#51 CDN rollout is
> parked in backlog, A11/A12 are live/closed, and B-012 is only runner-host
> hardening risk.
Alle Operator-Pending-Items aus `HANDOFF-2026-05-20.md` bleiben so:
- B-006 Cure53-Audit (Phase 06 Production-Gate)
- B-008 Disk-Pressure-Monitoring
- B-012 Gitea-runner Docker default-address-pool
- A6/A7/A9/A11/A12 env-flips aus `OPERATOR-CHECKLIST.md`
Plus die 14 Bucket-A Tasks (#16/#17 AV-Layer, #19/#20 Magic-Link, #23 Phase-06 audit, #26 TOTP, #29/#30/#32 Sentry-smoke, #40 PgBouncer, #41 R/W-Split, #51 CDN-Zone, #56 AI-Cost Stripe-meter, #65 Mobile App-Store, #27 Password-soft-banner) — alle weiterhin operator-pending, kein code work outstanding.
---
## 3. Bucket-B-Restbestand (verbleibender Scope nach den Quick-Wins)
| # | Track | Aufwand | Real verbleibender Scope |
| ----------- | ---------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **#38** | Shared-Store completion | ~2-3 Tage | Idempotency **erledigt** (`d4c14ab3`), Subscription-Cache **erledigt** (`81cfaa8b`). Offen: **nur noch Session-Store** sync→async. Höchstes Risiko im ganzen Track — `apiSessionStore` hat synchrone API (`createSession`/`getActiveSession`/`rotateSession`/`revokeSession`) die von vielen sync Route-Handlern + dem JWT-signing-flow konsumiert wird; die alle async zu machen kann einen Logout-Storm verursachen wenn falsch. Verdient eine eigene fokussierte Session. |
| **#42** | Outbox completion | ~1 Woche | call-site migrations, admin UI, CLI re-queue, e2e tests |
| **#53** | Feature-Flag rule-builder UI | 3-5 Tage | Visual rule-builder (JSON-textarea exists in `admin/feature-flags/engine.tsx`, drag-drop visual builder fehlt) — UI, braucht Browser-Verifikation |
| **#55** | AI-Cost Quota UI | 3-5 Tage | CLI **erledigt** (`6401bdbd`). Offen: Tenant-UI (`/app/$tenant/settings/ai-usage` Quota-Bars+Toggles) + Admin-UI (`/admin/tenants/$id/ai-quota` Override-Page) — UI, braucht Browser-Verifikation |
| **#59** | Realtime-Collab | ~1 Woche | Andere Editoren als Novel an Hocuspocus anbinden |
| **#72** | i18n migration sprint | 3-5 Tage | 111 hardcoded strings über 58 files extrahieren (`node scripts/i18n-audit.mjs --json` für aktuelle Liste). Mechanisch aber zeitintensiv. |
| **#73** | WCAG fix-sprint | 3-4 Tage | P0 + alle P1 **erledigt** (`ef7c53df`, `7358eb80`). Offen: 94 P2-Violations — Hauptbrocken `no-autofocus` (88, jeder braucht "programmatic focus on mount"-Judgment), `anchor-is-valid` (3, story-only), `media-has-caption` (2), `no-noninteractive-tabindex` (1). |
| **#76** | Test-Coverage ratchet | 5-10 Tage | Per-modul gates schrittweise hochziehen |
| **#21/#22** | Plugin Phase 1+2 | 2-3 Wochen | Hot-reload, marketplace, sandboxed iframe, 13 weitere hook-points |
| **F-002** | WASM per-instruction fuel | multi-week | Wasmtime-Swap ODER worker-thread + wall-clock kill |
Plus die Bucket-C Backlog-7 (#24, #52, #57, #64, #66, #74, #77).
### Bekannte pre-existing Test-Brüche (nicht von dieser Session verursacht)
- `packages/config/src/env-examples.test.ts` — 9 uncataloged `PLUGIN_*` keys in `.env.example` (Phase-06-Drift). Fix = die 9 Keys in `packages/config/src/catalog.ts` nachtragen; braucht Phase-06-Kontext für korrekte Klassifizierung.
- `apps/api` typecheck — 3 pre-existing Errors (`app.test.ts:114`, `stripe-webhook-route.test.ts:51`, `request-schemas.ts:250`). Nicht push-blocking (pre-push typecheck ist web-only).
---
## 4. Saubere Quick-Wins für nächste Session
Die 4 Quick-Wins aus dem ersten Handoff sind alle abgearbeitet (Section 1b). Verbleibende narrow Inseln:
1. **#78 Turnstile staging-verify** — kein Code, reine Operator-Aktion: Cloudflare Turnstile Site/Secret-Keys in staging env setzen, lead-capture mit echtem Browser testen. Schließt #78 endgültig.
2. **#62 Lost-Pixel Baseline-Bootstrap** — Operator-Aktion: `pnpm --filter @toolctrl/storybook build-storybook && pnpm --filter @toolctrl/storybook visual-regression:update`, dann `apps/storybook/.lostpixel/baseline/*.png` committen. Aktiviert den (aktuell self-skipping) `visual-regression` CI-Job.
3. **`env-examples.test.ts` reparieren** — 9 PLUGIN\_\* keys in den Config-Catalog nachtragen (siehe Section 3 "pre-existing Test-Brüche"). Braucht Phase-06-Kontext.
4. **#55 Tenant-UI / Admin-UI** — die Quota-Web-UIs. Echtes UI-Feature, braucht Dev-Server-Testing — kein Quick-Win, eher ein 3-5-Tage-Track.
---
## 5. Konventionen unverändert
Aus dem Vorgänger-Handoff alles weiter gültig:
- Alle commits direkt auf `main`. `git pull --rebase` vor Workflow-Start.
- Lefthook pre-commit (test-density / eslint-baseline / secrets / lint-staged) und pre-push (full `pnpm typecheck`) sind hart.
- React Router v7: Route-Type-Imports IMMER `./+types/<name>`, niemals relativ.
- Niemals `git add -A` — explizite Paths.
- Co-Author trailer: `Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>`
- `pnpm`, nicht npm. Tests via `npx vitest run <path>` nicht `pnpm test`.
---
## 6. Push-Status (jetzt-aktuell)
```
HEAD: 7358eb80 fix(a11y): clear all P1 jsx-a11y violations (#73)
origin/main: 7358eb80 (aligned nach Push)
worktree: nur auto-generated Prisma client modifications (packages/db/generated/prisma/*)
```
Diese Session total: ~16 commits gepusht. Blöcke: 6 (Tracks #78/#39/#62) + 4 Quick-Wins (#73-P0/#62-LostPixel/#38-Idempotency/#55-CLI) + 2 Subagent-Tracks (#38-subscription-cache/#73-P1) + Handoff-Updates.
---
## 7. Subagent-Workflow — was funktioniert hat
Sequenzielle Subagenten (einer pro Track, im Haupt-Worktree, orchestrator-reviewed nach jedem) funktionieren gut für **backend/mechanische Tracks** ohne Browser-Verifikationsbedarf. Belege: #38 subscription-cache (Subagent fand einen echten Cross-Replica-Bug den die Detail-MD nicht kannte) und #73 P1 (24 Files, alle 4 Rules auf 0).
**Was NICHT per Subagent-Swarm geht:**
- Parallele Subagenten im selben Worktree korrumpieren sich gegenseitig; Worktree-Isolation pro Track erzeugt 8 nicht-mergebare Branches mit Datei-Overlap (PROGRESS.md, Admin-Routes, hunderte tsx).
- **F-002** (Wasmtime-Swap) + **#21/#22** (Plugin Phase 1+2) sind echte Mehr-Wochen-Architektur — kein Subagent-Lauf liefert die zur Done-Bar; halbfertig = Projektregel-Verstoß.
- UI-Tracks (#53 builder, #55 UIs, #59) — Subagent kann coden, aber niemand kann ohne Dev-Server/Browser verifizieren. Ehrlich kennzeichnen, nicht als "completed" abhaken.
**Empfehlung für die nächste Session:** ein Subagent pro Track, sequenziell, immer reviewen. Reihenfolge nach Risiko/Verifizierbarkeit: erst #72 i18n (mechanisch), dann #38 Session-Store (sorgfältig, Auth-kritisch), dann #42 Outbox. UI-Tracks nur wenn der Operator Browser-Verifikation übernehmen kann.
---
**Ende des Handoffs.** Bei Unklarheit fragen, nicht raten.
@@ -0,0 +1,112 @@
# Handoff — Stand 2026-05-21
> **Historical snapshot only (2026-05-25 cleanup).** This file is preserved
> for audit/history. Do not treat its "start", "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:** #72 i18n-Extraction (2 Batches) + Worker-Crash-Fix + Lighthouse-CI-Rebuild — 5 Commits gepusht, Staging grün
**Ziel des Handoffs:** Nachfolge-Agent weiß in 5 Minuten wo wir stehen und kann einen der großen Tracks fokussiert aufnehmen.
---
## 0. Start hier (5-Minuten-Onboarding)
**Lies in dieser Reihenfolge:**
1. Dieses Dokument komplett.
2. `HANDOFF-2026-05-20b.md` + `HANDOFF-2026-05-20.md` — archivierter Bucket-A / Operator-Pending-Kontext.
3. `.claude/CLAUDE.md` — React-Router-v7-Konventionen, strikt enforced.
4. `AGENTS.md` im Repo-Root — Workflow + Branch-Strategie.
**Sofort-Sanity-Check (Repo-Root):**
```bash
git log --oneline -6 # HEAD sollte d1b2183a sein (oder neuer)
git status -s # nur packages/db/generated/** churn erwartet
git pull --rebase --autostash # andere Agenten arbeiten ggf. parallel
```
**Dann:** EINEN großen Track aus Section 3 wählen, fokussiert aufnehmen. Nicht mehrere parallel. Bei #38 zwingend eigene saubere Session (siehe Risiko-Hinweis).
---
## 1. Was diese Session bewegt hat (5 Commits auf `main`, gepusht)
`origin/main` = `d1b2183a`. Push-Range dieser Session: `c8b37a89..d1b2183a`.
| Commit | Was |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `35b7483a` | **#72 i18n Batch 1** — 65 hartcodierte JSX-Text-Strings über 42 `apps/web/app`-Dateien auf `ui.autogenerated.*`-Translation-Keys umgestellt (sha1-Suffix, Konvention der bestehenden 1335 Keys). EN-Werte + idiomatische deutsche Übersetzungen in beide `translations.json`. `verify-hardcoded-strings.mjs`-Baselines runter: `jsx-text` 85→18, `user-facing-prop-literal` 73→46, Lock-Test angepasst. |
| `7c36c00c` | **#72 i18n Batch 2** — 20 weitere gate-gezählte Strings über 7 Admin-/Route-Dateien (Tabellen-Header, `Card`/`Breakdown`-Props, 3 interpolierte `aria-label`s mit `{{value0}}`). Baselines: `jsx-text` 18→9, `user-facing-prop-literal` 46→35. |
| `a06c41ff` | **Worker-Crash-Fix** — `ioredis` in `apps/worker/package.json` deklariert. Der Worker bündelt `@toolctrl/shared-store` (importiert `ioredis` direkt) ins `dist/index.js`; `ioredis` war nur transitive Dep → unter pnpms isoliertem Linker nicht im Worker-Image → `ERR_MODULE_NOT_FOUND`, Crash-Loop. |
| `cff48bc4` | **Lighthouse-CI-Rebuild** — Workflow lief auf dem Gitea-Runner nie (kein Browser, kein Server, keine DB). Neu: auditet das deployte Staging (`boiler.saas-ctrl.com`), Gitea-Job installiert Chromium, Trigger = `schedule` (nächtlich) + `workflow_dispatch`. Neue `.lighthouserc.staging.json`. |
| `d1b2183a` | **Lighthouse: nur Performance gegatet** — Produkt-Entscheidung des Operators: B2B-SaaS, SEO irrelevant. `categories:performance` bleibt `error ≥0.95`; `seo` nicht mehr asserted; `accessibility`/`best-practices` → `warn`. Gilt für `.lighthouserc.staging.json` + `.lighthouserc.json`. |
**Verifiziert:** Worker healthy auf Staging, `deploy.yml` grün, `lighthouse.yml` grün (Run 7000). Web/API/Worker laufen alle auf `d1b2183a`.
---
## 2. Wichtige Erkenntnisse / Gotchas dieser Session
- **E-Mail-i18n ist eine Sackgasse, NICHT aufnehmen.** Untersucht: Transaktionsmails (`packages/mail/src/templates-react/transactional/`) sind **bewusst englisch** — `EmailTemplates.ts:20-36` dokumentiert `t`/`locale` als akzeptiert-aber-ignorierte No-ops; volle i18n wurde von der Phase-10-#75-React-Email-Migration explizit als „coordinated cross-cutting rewrite" verschoben. `mail.json` ist verwaistes Legacy. Sequenz-Mails (`packages/email-templates/src/sequences/*`) sind **totes Gerüst** — der Worker-`renderTemplate` ist ein `throw`-Stub (`email-sequence-runtime.ts:92`), `sendMail` fällt geschlossen. → Kein sauberer i18n-Task hier.
- **#73 a11y-Tooling ist inkonsistent.** `.eslintrc.a11y-baseline.json` verweist auf `scripts/verify-a11y-baseline.mjs` — **existiert nicht**. Scope (`apps/web/app/**`) vs. Rationale (`packages/ui` storybook) widersprüchlich. `anchor-is-valid` (3) / `no-noninteractive-tabindex` (1) reproduzieren sich nicht sauber. Vor #73-P2-Arbeit das Tooling klären/reparieren.
- **`no-autofocus` (88) ist KEIN mechanischer Sweep.** `autoFocus` → `useEffect`-Fokus umgeht nur die Lint-Regel, behebt das a11y-Problem nicht. Echte Lösung = 88 Einzelfall-Urteile (`eslint-disable` mit Begründung vs. entfernen).
- **i18n-Audit zählt auskommentierten Code.** `scripts/i18n-audit.mjs` scannt rohen Source inkl. `{/* */}`-Blöcke. Bei Batch 1 waren 16 von 111 „Treffer" in totem Code — bewusst NICHT migriert. Der enforced Gate (`verify-hardcoded-strings.mjs`) überspringt Kommentarzeilen korrekt. Audit-Floor steht bei 46 (30 gate-excluded Seed/Codegen/Legal-Pages + 16 auskommentiert).
---
## 3. Offener Track-Bestand + Empfehlung
Die sauberen Quick-Wins sind erschöpft. Alles Folgende ist substanziell — ein Track pro fokussierter Session.
| # | Track | Aufwand | Hinweis |
| ----------- | -------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **#38** | Shared-Store: Session-Store sync→async | 2-3 Tage | **HÖCHSTES RISIKO. Eigene saubere Session zwingend.** `apiSessionStore` hat synchrone API (`createSession`/`getActiveSession`/`rotateSession`/`revokeSession`), konsumiert von vielen sync Route-Handlern + JWT-signing-flow. Falsch gemacht = Logout-Storm auf Prod. Nur 1/6 Store offen (rate-limits ×2, idempotency, subscription-cache erledigt). |
| **#42** | Outbox completion | ~1 Woche | call-site migrations, admin UI, CLI re-queue, e2e tests. Admin-UI-Teil braucht Browser-Verifikation. |
| **#73** | WCAG P2 | 3-4 Tage | Erst Tooling reparieren (Section 2). Dann `no-autofocus` (88) per Einzelfall-Urteil. `media-has-caption` (2 in `AudioOrVideoPlayer.tsx`) = generische Komponente, vermutlich justified `eslint-disable`. |
| **#53/#55** | Feature-Flag-Builder / AI-Cost-UIs | je 3-5 Tage | UI-Tracks — brauchen Dev-Server/Browser-Verifikation. |
| **#76** | Test-Coverage ratchet | 5-10 Tage | Per-Modul-Gates hochziehen. |
| **#21/#22** | Plugin Phase 1+2 | 2-3 Wochen | Hot-reload, marketplace, sandboxed iframe, 13 hook-points. |
| **F-002** | WASM per-instruction fuel | mehrere Wochen | Wasmtime-Swap oder worker-thread + wall-clock kill. |
**#72 i18n ist abgeschlossen** (darum nicht mehr im Track-Bestand oben): mechanische Extraction, Namespace-Split (`billing`/`crm`/`auth`/`emailMarketing`) und E2E-Locale-Switch sind erledigt — Commits `a3885ed5` + `fa8b0e70` (Stand 2026-05-22 noch lokal, **nicht gepusht**). **Korrektur zum früheren Stand dieses Dokuments:** „Arabisch" war **nie ein geplanter Track**. Es taucht in `10-compliance-polish/i18n-foundation.md` ausschließlich als Beispiel auf — für Plural-Komplexität (6 Plural-Formen) und als RTL-Begründung. `supportedLngs` ist **DE/EN**; RTL existiert nur als Foundation mit 2 Storybook-Smoke-Tests (`dir="rtl"`-Toggle), siehe `10-compliance-polish/VERIFICATION.md`. Keine `ar`-Locale vorschlagen oder bauen.
**Empfehlung:** Als Nächstes **#38** in einer dedizierten, frischen Session. Sorgfältig: erst alle Call-Sites von `apiSessionStore` kartieren, dann async-Migration mit Tests pro Call-Site, kein Big-Bang.
### Offene Lighthouse-Restpunkte (klein, optional)
- Authentifizierte Routen (`/app/*`, `/admin/*`) werden noch nicht auditiert — braucht einen rotierten Staging-Session-Cookie als CI-Secret. Doku-Pfad in `docs/architecture/lighthouse.md` beschrieben.
- Der `Upload Lighthouse artifacts`-Step meldet `No files found .lighthouseci/` (kosmetisch — Reports liegen auf `temporary-public-storage`, Links im Job-Log).
---
## 4. Bucket-A / Operator-Pending (unverändert)
Historical note only: this 2026-05-21 operator-pending snapshot was superseded by `OPERATOR-CHECKLIST.md` and `PROGRESS.md`. In particular, A7/B2/#51 CDN rollout is now parked in backlog rather than active operator work.
**Bekannte pre-existing Test-Brüche** (nicht von dieser Session): `packages/config/src/env-examples.test.ts` (9 uncataloged `PLUGIN_*` keys), `apps/api`-typecheck (3 pre-existing Errors, nicht push-blocking).
---
## 5. Konventionen (unverändert)
- Alle Commits direkt auf `main`. `git pull --rebase --autostash` vor Workflow-Start (Worktree hat permanenten `packages/db/generated/**`-Churn).
- Lefthook pre-commit (test-density / eslint-baseline / secrets / lint-staged) und pre-push (full `pnpm typecheck`, ~50s) sind hart.
- React Router v7: Route-Type-Imports IMMER `./+types/<name>`, nie relativ.
- Niemals `git add -A` — explizite Paths. Achtung: `packages/db/generated/**` niemals mitcommitten.
- `pnpm`, nicht npm. Tests via `npx vitest run <path>`.
- Co-Author-Trailer: `Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>`
- Push deployt auto via Coolify auf Staging. CI-Status prüfbar via Gitea-DB-Query (siehe `docs/improvement-plan/archive/STAGING-ACCESS.md` Section "CI / Gitea-Actions Runner").
- `lighthouse.yml` triggert NICHT mehr auf Push — bei Bedarf via `workflow_dispatch` auslösen (curl-Command in `docs/improvement-plan/archive/STAGING-ACCESS.md`).
---
## 6. Operator-Profil-Notiz
Operator hat klargestellt: **SEO ist für dieses Produkt irrelevant** (B2B-SaaS, keine Search-Discoverability nötig). Keine Meta-Description-/Sitemap-/Structured-Data-Arbeit vorschlagen. Quality-Gates fokussieren auf Performance.
---
**Ende des Handoffs.** Bei Unklarheit fragen, nicht raten.
@@ -0,0 +1,152 @@
# Handoff — Stand 2026-05-24
> **Historical snapshot only (2026-05-25 cleanup).** This file is preserved
> for audit/history. Do not treat its "start", "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:** Bucket-1-Abbau + komplett-neue zentrale Observability/Sentry/Meilisearch/Loki-Infrastruktur. Viele Änderungen in der `toolctrl-labs/infra`-Repo (separates Gitea-Repo, NICHT der Boilerplate).
**Ziel des Handoffs:** Nachfolger weiß in 5 Minuten wo wir stehen und was als Nächstes kommt.
---
## 0. Start hier (5-Minuten-Onboarding)
**Lies in dieser Reihenfolge:**
1. Dieses Dokument komplett.
2. `HANDOFF-2026-05-21.md` für den davor liegenden archivierten Stand (#72-i18n + Lighthouse-CI-Rebuild + Worker-Crash-Fix).
3. **Wichtig: das `toolctrl-labs/infra`-Repo auf Gitea.** Die ganze zentrale Infra (Observability, Sentry, Meilisearch, Loki, WireGuard-Mesh) ist DORT dokumentiert, nicht im Boilerplate. Clone via `git clone https://git.tool-ctrl.de/toolctrl-labs/infra` und lies README.md + STANDARDS.md.
4. `.claude/CLAUDE.md` — React-Router-v7-Konventionen, strikt enforced.
**Sofort-Sanity-Check:**
```bash
git log --oneline -6 # HEAD = fa8b0e70, dahinter 1-2 lokale doc-commits dieser session
git status -s # erwartet: packages/db/generated/** churn + ggf. neue handoff/progress edits
git pull --rebase --autostash # andere Agenten arbeiten ggf. parallel
```
**Lokale unpushed Commits beachten:** Schon zu Session-Start lagen 2 Commits vor (`a3885ed5` Namespace-Split, `fa8b0e70` E2E-Locale-Switch für #72) die noch nicht auf `origin/main` sind. Plus die Doc-Edits dieser Session (PROGRESS.md + neues Handoff). Wenn du pushst, deployt Coolify automatisch — bei Doc-Only-Edits unkritisch, aber bewusst entscheiden.
---
## 1. Was diese Session bewegt hat
### 1.1 Bucket-1-Abbau (Operator-Pending-Items)
| Item | Vorher | Jetzt |
| --------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| #41 Read-Replica | „replica-deploy-pending" | als bewusst zurückgestellt dokumentiert (Single-DB-Fallback aktiv, kein Funktionsverlust) |
| #78 Turnstile | nicht aufgesetzt | live aufgesetzt + per Negativ-Test verifiziert. Sicherheits-Fazit: aktuell nicht zwingend nötig weil keine öffentlichen Landingpages, aber Backend ist live |
| #51 CDN | historical rollout parked | **backlogged** — Origin in Nürnberg + DACH-Audience + Cloudflare-Proxy reicht. Reaktivieren wenn internationale Kunden / große Media / Traffic-Spitzen |
| #56 Stripe-Meter | „stripe-account-setup-pending" | **deferred** — noch keine zahlenden Overage-Kunden |
| B3 (bcrypt-rehash) | nie live getestet | **verifiziert** — Login als `staging-admin@saas-ctrl.com` hat den Hash sauber von bcrypt auf argon2 umgesprungen. Dual-Mode-Code aus #28 funktioniert |
| B5 Disk-Alert | „operator-config-pending" | **erledigt** — Coolify-Discord-Webhook aktiviert, Disk-Trigger an |
| #23 Plugin Phase 3 (Cure53) | „operator-audit-pending" | **deferred** — Budget aktuell nicht da. Konsequenz im PROGRESS-Row notiert: Plugin-System geht NICHT in Produktion bis Audit + Sign-off durch sind |
### 1.2 Zentrale Infrastruktur neu aufgebaut
**Was es vorher gab:** je Projekt eigener Side-Stack (Grafana+Prometheus auf Staging, Sentry auf Staging, Meilisearch auf Staging). Skalierte nicht für mehrere SaaS.
**Was jetzt steht:**
- **WireGuard-Mesh** `10.42.0.0/24` mit `control` als Hub, Peers `homeserver` (10.42.0.2), `boilerplate-staging` (10.42.0.3), `node1`/EX44 (10.42.0.4). IP-Forwarding und FORWARD-Chain auf control eingerichtet. ADR 008 im infra-Repo.
- **Zentrales Grafana + Prometheus** auf `control` unter `https://grafana.saas-ctrl.com`. Scrapt jede Host-Node-Exporter + Docker-Stats-Exporter über das Mesh. Vier Project-Dashboards (Boilerplate, saas-ctrl.com, Homeserver, Hetzner Dedicated EX44). Admin-Pass auf `control:~/.cli-tokens/central-grafana-admin`.
- **Zentrales Sentry** auf `node1`/EX44 unter `https://sentry.saas-ctrl.com`. Self-hosted Sentry-Stack hinter Caddy (TLS via Let's Encrypt). Org `sentry`, Team `boilerplate` mit Projekten `api`/`worker`/`web`. Boilerplate-Coolify-Envs zeigen auf neue DSNs + OTEL-Endpoint. SENTRY_AUTH_TOKEN rotiert in Coolify + Gitea-Secrets. Admin-Pass auf `control:~/.cli-tokens/central-sentry-admin`, DSNs unter `central-sentry-dsns`, Auth-Token unter `central-sentry-auth-token`. **Altes Sentry auf Staging läuft noch** — bewusst stehen gelassen, kann jetzt aber abgebaut werden, frisst ~4 GB RAM.
- **Zentrales Meilisearch** auf `node1`/EX44 auf `10.42.0.4:7700`. Boilerplate-Apps zeigen via Coolify-Env auf den neuen. Alter Container auf Staging gestoppt + entfernt, Volume zur Sicherheit behalten. Master-Key auf `control:~/.cli-tokens/central-meilisearch-master-key`. **Beide Instanzen waren leer beim Switch** — niemand hatte auf Staging je Daten geschrieben die in Meili landen würden.
- **Zentrales Loki + Promtail** auf jedem Host. Loki auf EX44 `10.42.0.4:3100`, Promtail auf allen vier Hosts schickt Container-Logs hin. Als Grafana-Datasource registriert. In Grafana → Explore → Loki auswählen → `{server="..."}`-Queries möglich.
**Wichtige Lesson learned:** Docker port-publishing (`-p 10.42.0.4:7700:7700`) mit UFW + Docker-iptables auf EX44 funktioniert NICHT für Traffic von wg-Peers. Mittel zur Wahl auf EX44 ist `--net=host` plus explizites Binding auf die Mesh-IP. Pattern in infra-Repo dokumentiert.
### 1.3 Infra-Repo `toolctrl-labs/infra` massiv erweitert
**Pushes:** `69636e7`, `6d26a84`, `dcf8ca1`, `174b9a9` auf `main`.
- `README.md` — neue Sektionen: Central observability, WireGuard mesh, Central Sentry, Central Meilisearch, Central logs (Loki). Hosts-Übersicht aktualisiert (node1 hat jetzt Sentry, boilerplate-staging hinzugefügt, control hat zentrale Stacks). DNS-Records für grafana.saas-ctrl.com + sentry.saas-ctrl.com.
- `STANDARDS.md` (neu) — verpflichtende Regeln für jeden SaaS im Estate. 11 Sections: zentrale Sentry-Nutzung, Host-Pflicht (Metrics+Logs), Per-Project-Dashboard, zentrale Meilisearch, Admin-SSO über Authentik, Repos in Gitea, Coolify-Konventionen, Cloudflare, Secrets, Backups, ADR-Norm.
- `decisions/008-central-observability-and-sentry.md` (neu ADR) — begründet zentrale Architektur + WireGuard-Mesh (revisiert ADR 004).
- `runbooks/add-host-to-central-observability.md` (neu) — Schritt-für-Schritt für neuen Host ans Mesh + Exporters + Prometheus-Targets.
---
## 2. Was JETZT als Nächstes zu tun ist
### Sofort sinnvoll, Bucket-1-Restposten:
**B7 — Tenant-Snapshot-Verify** ist der einzige Bucket-1-Punkt der noch echt offen ist und den ein Agent ausführen kann. ABER hat zwei Hürden die vorher gelöst werden müssen:
1. Die `toolctrl-cli` ist nicht im Production-Image — auf Staging müsste der Repo geklont und Dependencies installiert werden, oder ein dediziertes CLI-Image gebaut werden.
2. S3/MinIO ist auf Staging nicht installiert. Entweder ein MinIO-Container dazustellen oder ein lokales Filesystem-Backend für die CLI nutzen (falls supportet).
Empfehlung: MinIO auf Staging hinzufügen ist ein 20-Minuten-Job (analog zum Meilisearch-Pattern auf EX44, Host-Network mit Mesh-IP-Bind), dann CLI aus den Repo-Sources laufen lassen, snapshot+restore round-trippen, Row-Counts vergleichen.
**Worker-Groups-Side-Finding (superseded)** — historical 2026-05-24 note: at that point staging only ran the `general` worker group. This was closed by the 2026-05-25 persistent worker-group provisioning; the current staging topology is five separate Coolify worker services (`general`, `mail`, `import`, `webhook`, `plugin`). See `docs/ops/worker-queues.md` and `docs/improvement-plan/archive/STAGING-ACCESS.md`.
### Bucket 2 — Code fertig, nur Live-Verifikation
| # | Task | Was zu tun |
| --- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| #19 | Magic-Link-Reset | Core flow + MailerSend smoke live-grün: token issued, queued, temporary mail worker completed provider send, consumed, replay rejected. **2026-05-25 addendum:** persistent Coolify worker-group provisioning landed; B-014 resolved and #19 closed. |
| #26 | TOTP-MFA | Erledigt 2026-05-24: MFA-Enroll + TOTP-Challenge + Recovery-Code-Challenge + Cleanup auf Staging grün. |
### Bucket 3 — wartet auf Externe
| # | Task | Was hängt |
| --- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| #23 | Plugin Phase 3 | Cure53-Audit budget-deferred (siehe oben). Wenn Geld frei wird: `scripts/build-plugin-audit-package.sh` + Versand an Cure53 (oder Alternativvendor) |
| #65 | Capacitor Mobile | Native Builds brauchen Mac+Xcode+Android-Studio. App-Store + Play-Store Submission. Apple Dev Account ($99/Jahr) + Google Play Console ($25 einmalig) |
### Bucket 4 — echte Code-Arbeit, die großen Tracks
**Kleine deferrte Follow-ups (je < 1 Tag):**
- #20 Magic-Link-Invitation — `User.passwordHash`-nullable-Migration
- #27 Password-Policy — Login-Soft-Banner
- #39 Pub/Sub Cache — Reconnect-Flush + Testcontainers-Integrationstest
**Großtracks (ein Track pro fokussierter Session):**
- **#38** Shared-Store: Session-Store sync→async — 2-3 Tage, **höchstes Risiko**, eigene saubere Session zwingend
- **#42** Outbox completion — ~1 Woche, Call-Site-Migrationen + Admin-UI + CLI re-queue + E2E
- **#53** Feature-Flag-Builder — Visual Rule-Builder-UI + Affected-Count-Endpoint + Kill-Switch + 4 v1-Callsites
- **#55** AI-Cost Phase 2 — Admin- + Tenant-Web-UIs (Engine fertig)
- **#59** Realtime-Collab — Snapshot/Cleanup-Cron + Presence-Bar-UI + Permission-Helper + Rows-/Workflow-Editor-Integration
- **#21 + #22** Plugin Phase 1+2 — Hot-reload, Marketplace, sandboxed iframe, weitere 13 Hook-Points (NICHT prod-rollen ohne Cure53-Audit)
- **#62** Storybook — Lost-Pixel Visual-Regression, Toolbar-Globals, Tailwind-v4-Pipeline
- **#73** WCAG P2 — `no-autofocus` (88) per Einzelfall-Urteil; `verify-a11y-baseline.mjs` muss vorher repariert/erstellt werden
- **#76** Test-Coverage — Per-Modul-Gates auf 85-95% kritische Pfade hochziehen
- **#17** FileObject-Scan-Columns — von Bucket 1 reklassifiziert als echtes Code-Work: Scan-Spalten am `FileObject`-Model fehlen komplett, plus Scan-Result-Persistenz + User-Notification + Audit-Events sind nicht gebaut. Detail-MD `01-tech-debt-foundation/av-scanner-layer-2.md` ist Wahrheit, der Status-String im PROGRESS war irreführend
### Housekeeping (lose Enden dieser Session)
- **Altes Sentry auf Staging stoppen** — `boilerplate-staging:/opt/sentry-stack/` läuft weiter und frisst ~4 GB RAM, obwohl alle Apps schon zum neuen umgelenkt sind. Wenn Verifizierung gesehen wurde dass das neue stabil ist, alten Stack mit `docker compose down` runterfahren. Volume bewusst behalten falls Rollback nötig.
- **2 unpushed `#72`-Commits** auf Boilerplate (`a3885ed5`, `fa8b0e70`). Beide sind sauber, wurden aber nie gepusht. Wenn du sie weghaben willst, einfach `git push`.
- **PROGRESS.md** hat in dieser Session 3 Doc-Edits bekommen (#41/#51/#23 Status-Deferrals). Auch noch nicht committed/gepusht. Ich committe sie zusammen mit diesem Handoff.
- **Coolify-Env-Duplikate** — Coolify's API erzeugt mit PATCH neue Einträge statt zu updaten. Auf den 3 Boilerplate-Apps liegen ein paar duplizierte Envs (z.B. `SEED_ADMIN_EMAIL`/`SEED_ADMIN_PASSWORD`). Funktional fängt Coolify den letzten Wert ab, kosmetisch unsauber. Bei Gelegenheit über die Coolify-API per DELETE aufräumen.
- **Marketing-VM** ist noch nicht im zentralen Monitoring. Kein SSH-Key registriert. Wenn das in den Mesh soll: Runbook in der `infra`-Repo unter `runbooks/add-host-to-central-observability.md`.
---
## 3. Konventionen (unverändert, aber wichtig)
- Alle Commits direkt auf `main`. `git pull --rebase --autostash` vor Workflow-Start.
- Lefthook pre-commit (test-density / eslint-baseline / secrets / lint-staged) und pre-push (full `pnpm typecheck`, ~50s) sind hart.
- React Router v7: Route-Type-Imports IMMER `./+types/<name>`, nie relativ.
- Niemals `git add -A` — explizite Paths. `packages/db/generated/**` niemals mitcommitten.
- `pnpm`, nicht npm. Tests via `npx vitest run <path>`.
- Co-Author-Trailer: `Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>`
- Push deployt auto via Coolify auf Staging.
- **NEU: Wenn etwas Infra-mäßig ist, gehört es ins separate `toolctrl-labs/infra`-Repo, nicht ins Boilerplate.** Boilerplate-Repo ist nur für die SaaS-Codebase.
---
## 4. Operator-Profil-Notiz
- B2B-SaaS, SEO irrelevant (alte Note bleibt gültig)
- Antwortstil: kurz, plain, keine Tabellen-Wände, keine Emojis, keine inline-Code-Formatierung für Dinge die nicht Code sind (Pfade, URLs, Env-Var-Namen als Fließtext). Ein Item nach dem anderen abarbeiten, nicht alle Buckets gleichzeitig dumpen.
---
**Ende des Handoffs.** Bei Unklarheit fragen, nicht raten.
@@ -0,0 +1,326 @@
# 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:**
```bash
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.
#### 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:**
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
```bash
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
```bash
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
```bash
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:
```bash
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
```bash
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.:
```ts
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.
@@ -0,0 +1,211 @@
# 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`.
### Task A — #20 Magic-Link Invitation / passwordHash nullable
- `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/<Model>.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.
@@ -0,0 +1,37 @@
# Historical Handoffs
This directory keeps archived handoff snapshots from earlier improvement-plan
agent runs. They are retained for audit and context only; improvement-plan
reconciliation lives in [`../../PROGRESS.md`](../../PROGRESS.md) and
[`../../OPERATOR-CHECKLIST.md`](../../OPERATOR-CHECKLIST.md). Current deploy
and worker topology lives in `docs/deployment.md`, `docs/worker.md`, and
`docs/ops/worker-queues.md`.
Do not execute instructions from these archived files directly. Many entries
capture time-bound deploy notes, temporary blockers, or "continue now" prompts
that were superseded by later commits and runbooks. Treat them as historical
evidence only, then verify the current status through the canonical docs linked
above and the live codebase.
Individual handoff bodies may contain stale blocker lists; prefer this README
plus the current checklist when reconciling status.
Status-sensitive areas have their own current sources:
- Email Sequences: `docs/features/email-sequences.md`.
- Plugin runtime and Plugin System: `docs/features/plugins.md`,
`docs/operations/plugin-lifecycle.md`, and
`docs/security/plugin-runtime-signoff.md`.
- Workflow Engine: `docs/feature-inventory.md`,
`docs/feature-manifests/plugin-candidates.json`, and
`docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md`.
- Coolify workers and mail worker topology: `docs/deployment.md`,
`docs/worker.md`, and `docs/ops/worker-queues.md`.
## Index
- [`HANDOFF-2026-05-20.md`](HANDOFF-2026-05-20.md) — Stand 2026-05-20.
- [`HANDOFF-2026-05-20b.md`](HANDOFF-2026-05-20b.md) — Stand 2026-05-20, Session B.
- [`HANDOFF-2026-05-21.md`](HANDOFF-2026-05-21.md) — Stand 2026-05-21.
- [`HANDOFF-2026-05-24.md`](HANDOFF-2026-05-24.md) — Stand 2026-05-24.
- [`HANDOFF-2026-05-25.md`](HANDOFF-2026-05-25.md) — Stand 2026-05-25, autonomer Nacht-Modus.
- [`HANDOFF-2026-05-26.md`](HANDOFF-2026-05-26.md) — Stand 2026-05-26.