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

25 KiB
Raw Blame History

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):

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.