198 lines
25 KiB
Markdown
198 lines
25 KiB
Markdown
# 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.
|