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

198 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.