Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/05-business-features/VERIFICATION.md
T

29 KiB

Phase 05 — Verification Report

Historical report: This file verified the Phase-05 plan quality on 2026-05-16. It is not the production-readiness source of truth. Later closeout docs, feature docs, runbooks, and docs/ops/asset-cdn.md supersede claims that read like live status, especially CDN/SRI and email-sequence delivery.

Verifier: Phase-05-Verifier (Read-Only) Datum: 2026-05-16 Scope: README.md + 9 Task-Detail-MDs (10 Files total) Result: PASS mit Minor-Findings — keine Blocker; einige inhaltliche Lücken adressierbar während Execution.


1. Template-Konformität

Section-Reihenfolge (laut DETAIL-MD-TEMPLATE.md)

File Frontmatter Problem Depends on Blocks Approach Impl Steps Tests Acceptance Rollback Security Subagents Staging Deviations Progress Log Lessons Learned
feature-flags.md OK OK OK OK OK OK OK OK OK OK OK OK OK OK — (optional, fehlt)
ai-cost-phase-1.md OK OK OK OK OK OK OK OK OK OK OK OK OK OK —
ai-cost-phase-2.md OK OK OK OK OK OK OK OK OK OK OK OK OK OK —
ai-cost-phase-3.md OK OK OK OK OK OK OK OK OK OK OK OK OK OK —
form-widget.md OK OK OK OK OK OK OK OK OK OK OK OK OK OK —
realtime-collab.md OK OK OK OK OK OK OK OK OK OK OK OK OK OK —
marketing-funnel-phase-1.md OK OK OK OK OK OK OK OK OK OK OK OK OK OK —
marketing-funnel-phase-2.md OK OK OK OK OK OK OK OK OK OK OK OK OK OK —
marketing-funnel-phase-3.md OK OK OK OK OK OK OK OK OK OK OK OK OK OK —

Lessons Learned ist laut Template optional (Z. 128: "Lessons Learned (optional)"). Konsistent über alle 9 Files weggelassen → akzeptabel.

Finding T1 (Info): Alle 9 Detail-MDs erfüllen die 14 Pflicht-Sections in korrekter Reihenfolge. README.md folgt eigenem Phase-Schema (kein Detail-MD-Template) — wie geplant.


2. Dependencies-Konsistenz

feature-flags.md zuerst → blocked-by-Liste

feature-flags.md ist als Foundation deklariert. Tatsächliche Konsumenten:

  • ai-cost-phase-1.md Depends: feature-flags.md (für ai-usage-dashboard Flag) ✓
  • ai-cost-phase-2.md Depends: feature-flags.md (für ai-quota-soft-degradation) ✓
  • ai-cost-phase-3.md Depends: feature-flags.md (für Per-Tenant-Overage-Enablement) ✓
  • form-widget.md Depends: feature-flags.md (für Turnstile-Gradual-Rollout) ✓
  • realtime-collab.md Depends: feature-flags.md (für Plan-Tier-Gating) ✓
  • marketing-funnel-phase-1.md Depends: feature-flags.md (Turnstile Gradual-Rollout) ✓
  • marketing-funnel-phase-2.md Depends: feature-flags.md (Outbound-Integration opt-in) ✓
  • marketing-funnel-phase-3.md Depends: feature-flags.md (Sequence-Aktivierung) ✓

→ konsistent.

AI-Cost-Phasen sequenziell (1 → 2 → 3)

  • Phase 2 Depends on Phase 1 ✓ (Z. 24: "AICostEvent-Pipeline + TenantAICostSummary als Datengrundlage")
  • Phase 3 Depends on Phase 2 + Phase 1 ✓ (Z. 24-25)
  • Phase 1 Blocks Phase 2 + Phase 3 ✓
  • Phase 2 Blocks Phase 3 ✓

Marketing-Funnel-Phasen sequenziell (1 → 2 → 3)

  • Phase 2 Depends on Phase 1 (Z. 23) ✓
  • Phase 3 Depends on Phase 2 (Z. 23) + Phase 1 ✓
  • Phase 1 Blocks Phase 2 + Phase 3 ✓
  • Phase 2 Blocks Phase 3 ✓

React-Email aus Phase 10 für marketing-funnel-phase-3.md

  • Z. 28: "MUSS aus Phase 10 vorgezogen werden ... Alternative: minimaler HTML-Fallback bis React-Email regulär kommt, dann Migration." ✓
  • Implementation-Step 1 (Z. 56-59): explicit "React-Email-Vorziehung (aus Phase 10)" als optionaler Stub ✓
  • README.md verweist auf ../10-compliance-polish/react-email.md (Z. 109) ✓
  • Konsistent mit 00-execution-order.md Z. 106: "react-email.md kann früher gezogen werden falls Phase 05 Marketing-Funnel-Phase-3 sie braucht" ✓

AI-Cost-Phase-1 braucht Outbox aus Phase 03

  • Phase 1 Depends: 03-scaling-infrastructure/outbox-pattern.md (#42) ✓ (Z. 29)
  • Phase 1 Depends: worker-queues.md (#43) ✓
  • Phase 1 Depends: read-write-split.md (#41) ✓
  • Phase 1 Depends: metrics-grafana.md (#14) ✓

feature-flags.md braucht SharedStore aus Phase 03

  • Depends: 03-scaling-infrastructure/shared-store-package.md (#37) ✓ (Z. 29)
  • Depends: 03-scaling-infrastructure/pubsub-cache-invalidation.md (#39) ✓
  • Depends: 02-observability/sentry-wiring-api-worker.md (#11) ✓

Finding D1 (Info): Alle Dependencies konsistent zwischen README.md, 00-execution-order.md und den einzelnen Detail-MDs. Keine zirkulären Verweise.

Finding D2 (Minor): realtime-collab.md referenziert 02-observability/opentelemetry.md (#13) — korrekt, aber die Blocks-Sektion ist sehr dünn ("Spätere Erweiterung auf andere Editoren ... sind out-of-scope"). Kein echter Folge-Task wird hard-blockiert; akzeptabel, weil README Track-B als "Standalone" markiert.


3. Implementation-Steps-Qualität

Feature-Flags-Targeting-Engine

Erwartet: Composite-Rules (AND/OR-tree), Percentage-Sticky via SHA1-Hash, JSON-Variants.

  • Step 2 (Z. 64): "Targeting-Engine ... evaluateRule(rule, ctx) mit Support für: boolean, allowlist, percentage (sticky-hash), plan-tier, role-based, time-based, composite (AND/OR/NOT mit Child-Rules). Pure Function, vollständig unit-testbar ohne DB." ✓
  • Step 3 (Z. 67): "evaluateFlag + getFeatureFlagVariant Public-API ... orchestriert Storage-Load, Dependency-Resolution (Parent-Flag-Check), Targeting-Eval, Variant-Auswahl. Strikt typisierte Return-Werte." ✓
  • Approach Z. 56: "Percentage-Rollout via SHA1(userId+flagName) % 100: sticky pro User-Flag-Kombi" ✓
  • Step 5 (Z. 73): Visueller Rule-Builder, Percentage-Slider, Allowlist-Search, Variant-JSON-Editor mit Monaco + Schema-Validation ✓
  • Test Z. 90: "percentage-hash.test.ts — sticky-Test: gleicher (userId, flagName) liefert immer gleichen Bucket; Distribution-Test über 10k Sample-IDs liegt bei N% innerhalb ±2%" ✓

Finding I1 (Minor): Hash-Algo wird in Approach als "SHA1" benannt, in Tests aber nicht explizit als SHA1 vs SHA256 fixiert. Empfehlung: in Step 2 explizit fixieren (SHA-256 wäre moderner — SHA1 ist aber für Bucket-Hashing vollkommen ausreichend; egal welche Wahl, sollte konsistent dokumentiert sein).

AI-Cost-Wrapper um LLM-Calls

Erwartet: Wrapper in allen Pfaden — chatbot-stream, generate-action, PromptBuilderService, RAG-Embedding.

  • ai-cost-phase-1.md Problem-Section Z. 20-23 listet alle 4 Stellen mit Datei + Line ✓
  • Implementation Step 4 (Z. 67-73) instrumentiert alle 4 atomisch (eigener Commit pro Call-Site) ✓
  • Wrapper-Signatur explizit (Z. 64): executeLLMCall({ provider, model, capability, ctx, run }) mit Idempotency-Key ✓
  • Provider-Wrapper liefert sinnvolle Inheritance: Provider-Usage-Numbers nutzen wenn vorhanden, sonst countTokens ✓

Finding I2 (Info): Vollständige Coverage der vier bekannten LLM-Pfade. Subagent-Recommendation (Z. 146-148) erinnert explizit, weitere Stellen mit Explore-Subagent zu suchen — guter Defensive-Step.

Stripe-Meter-Events mit Reconciliation-Cron

  • Implementation Step 4 (Z. 61-63): Nightly Cron, Idempotency-Identifier (UUID), submittedToStripe=true-Flag, stripeMeterEventId gespeichert ✓
  • Implementation Step 7 (Z. 70-72): AIOverageSubmission-Audit-Trail-Model ✓
  • Implementation Step 8 (Z. 73-75): Monatlicher Reconciliation-Cron, >1% Mismatch → Alert + Sentry-Capture, Runbook in Doku ✓
  • Approach Z. 47-48: Begründung Nightly statt Realtime (Stripe-Quotas) + Block-Cents-Aggregation (Mikro-Charges vermeiden) ✓
  • Security Note Z. 131: "Idempotency-Identifier (UUID pro Submission) ist Pflicht — Stripe deduped auf Identifier. Tests müssen explizit Retry-Pfad verifizieren." ✓
  • Rollback-Strategy Z. 124-127 inkl. AI_OVERAGE_SUBMISSION_ENABLED=false Killswitch + Backfill-Run ✓

→ Robust dokumentiert.

Form-Widget mit CSP-safe iframe + SRI

  • Approach Z. 45-47: "CDN-served loader-Script <3KB ... sandboxed iframe ... CSP-safe ... SRI für Tamper-Detection" ✓
  • Implementation Step 3 (Z. 66-68): Bootstrap-Loader mit SRI-Hash-Output für Embed-Code-Generator ✓
  • Implementation Step 4 (Z. 69-71): Embedded-Form-App im iframe (separater Bundle <80KB gzipped) ✓
  • Implementation Step 8 (Z. 81-83): Embed-Code-Generator mit integrity="sha384-..." Attribute ✓
  • Security Note Z. 151: CSP-Header für Embed-iframe definiert ("default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'") ✓
  • Security Note Z. 145: XSS-Mitigation (React default + Zod-Validation, kein freier HTML in Labels) ✓
  • Acceptance-Criterion Z. 122: PostMessage-Events toolctrl:form:submitted/error/resize ✓

Finding I3 (Minor — siehe Lücken-Section 8): Step 3 erwähnt toolctrl:form:resize für dynamic-height aber kein detailliertes Protokoll. Empfehlung siehe Lücken-Section.

Hocuspocus mit Graceful-Degradation

  • Approach Z. 40-41: "Graceful-Degradation — wenn HOCUSPOCUS_URL nicht gesetzt oder Service unreachable, Editor läuft als Single-User mit existing REST-Save" ✓
  • Implementation Step 8 (Z. 73-75): "Editor-Wrapper prüft Connection-State: bei disconnected > 10s zeige subtilen Status ... fallback auf REST-Save ... Wenn HOCUSPOCUS_URL env nicht gesetzt: Editor läuft komplett Single-User wie vorher (kein Provider initialisiert)" ✓
  • Acceptance-Criterion Z. 113: "Graceful-Degradation: ohne HOCUSPOCUS_URL läuft Editor Single-User, mit Service-Down zeigt Offline-Indikator" ✓
  • Rollback Z. 125-128: drei Disable-Optionen (Flag, Env, Container-Removal) ✓
  • E2E-Test Z. 97: "Offline-Test: Hocuspocus-Container stoppen → User sieht Offline-Indikator → Tippt weiter → Container zurück → Re-Sync ohne Datenverlust" ✓

→ Vollständig adressiert.

Marketing-Funnel Lead-Capture (CORS + Anti-Spam)

  • Implementation Step 2 (marketing-funnel-phase-1.md Z. 56): CORS-Whitelist gegen MARKETING_DOMAINS env, Honeypot, Turnstile, Rate-Limit (5/min/IP + 3/min/Email), Duplicate-Dedup-Logic ✓
  • Approach Z. 45-48: explicit Defense-in-Depth-Begründung ✓
  • Security Notes Z. 130-135: PII-Handling, Honeypot-Field-Naming aus Env, CORS als nur-Browser-Defense (Server-Bots umgehen → Rate-Limit zwingend), Email-Enumeration-Schutz, GDPR-Consent-Mechanismus, IP-Logging-Doku ✓

→ Robust.

Self-Service-Conversion-Flow (Lead → Tenant via signed-Token)

  • marketing-funnel-phase-2.md Implementation Step 1 (Z. 53-55): Signed-Lead-Token mit HMAC-SHA256, 7d-TTL ✓
  • Step 3 (Z. 59-61): Atomic Conversion-Service in Postgres-Transaction mit (a) Tenant-Create (b) Lead-Update (c) TenantAcquisition (d) Outbox-Event (e) Audit ✓
  • Step 5 (Z. 65-67): Signup-Action-Integration ruft Conversion-Service ✓
  • Security Notes Z. 141-147 adressieren: Token-Replay (Idempotency via convertedToTenantId-Check), Email-Read-Only-bei-Pre-Fill (Lead-Hijacking-Schutz), Race-Condition (Unique-Index auf Lead.convertedToTenantId) ✓

→ Sicher.


4. Test-Requirements-Qualität

Per-Feature Konkretheit

Alle 9 Files haben strukturierte Test-Sections: Unit / Integration / E2E mit konkreten Cases. Coverage-Targets numerisch (z.B. 90% für packages/ai/src/cost/, 80% für Worker-Handlers).

E2E-Tests für Lead-Conversion-Flow

  • marketing-funnel-phase-2.md Z. 101-105 spezifiziert:
    • SDK + Form-Submit → Lead → Admin "Convert to Tenant" → Tenant erscheint
    • Self-Service-Flow: Capture → signed-Token-Link → pre-filled Signup → completed → Tenant + Welcome-Email
    • Integration-UI: Slack-Webhook → Test-Send-Button → Mock-Slack empfängt
    • Funnel-Report: Test-Daten mit definierter Source/Campaign → Reports zeigen korrekte Conversion-Rates ✓

Multi-User-Tests für Realtime-Collab

  • realtime-collab.md Z. 91-93 (Integration) + Z. 95-98 (E2E):
    • Two-Browser-Tab-Test: User A tippt → User B sieht innerhalb 1s; Cursor sichtbar
    • Awareness mit zwei User-States
    • Offline/Re-Sync-Test
    • Permission-Refusal-Test ✓
  • Staging-Test Z. 174: "Last-Test: 10 simultane Connections auf gleichem Doc — Sync-Latenz <300ms p95" ✓

Finding T2 (Info): Test-Sections sind konsistent qualitativ hochwertig. Coverage-Gates klar pro Modul-Scope.


5. Staging-Deployment-Steps

Hocuspocus-Container

  • realtime-collab.md Z. 155-168: docker-compose-Snippet mit Image, Env, Ports, depends_on, Traefik-Label für wss://collab.staging.toolctrl.de ✓
  • TLS-Termination + Subdomain-Routing dokumentiert ✓
  • Last-Test-Anweisung 10 concurrent connections ✓

Form-Widget CDN-Upload

  • form-widget.md Z. 169: "Asset-CDN (aus Phase 03 #46) muss bereit sein; Loader-Build-Output dorthin deployed (CI-Step)" ✓
  • form-widget.md Implementation Step 3 (Z. 66-68): Build via esbuild/vite, SRI-Hash-Output ✓
  • Bundle-Size-Verify: widget.js < 3KB gzipped via curl-Check ✓
  • Cross-Browser-Smoke ✓

Marketing-SDK-CDN

  • marketing-funnel-phase-1.md Z. 152: "Asset-CDN für marketing.js deployed (CI-Step)" ✓
  • Implementation Step 4 (Z. 62-64): CI-Step erweitert mit versioniertem Pfad (marketing.v1.js) + Latest-Symlink + SRI-Hash ✓
  • Bundle-Size-Verify <5KB gzipped via curl ✓

Finding S1 (Info): Alle drei Externe-Asset-Deployments haben klare Staging-Steps. CI-Workflow-Files (.github/workflows/deploy.yml) als Touchpoint dokumentiert.


6. Konsistenz mit User-Wünschen

"Vollausbau Feature-Flags" — 9 Aspekte

Original-Wunsch laut Phase-Scope: Gradual-Rollouts, Plan-Tier-Gating, A/B-Tests (Multi-Variant), Killswitches mit Time-Boxing, Dependency-Hierarchien.

Spec liefert 7 Targeting-Rule-Types (Z. 64) + 5 Killer-Patterns (Z. 82):

  1. boolean ✓
  2. allowlist (tenantIds/userIds/emails) ✓
  3. percentage (sticky-hash) ✓ → Gradual-Rollouts
  4. plan-tier ✓ → Plan-Tier-Gating
  5. role-based ✓
  6. time-based (enabledFrom/until) ✓ → Killswitches mit Time-Boxing
  7. composite (AND/OR/NOT mit Child-Rules) ✓
  • Variants ✓ → A/B-Tests
  • parentFlagId / Dependency-Resolution ✓ → Dependency-Hierarchien
  • Audit-Trail ✓

→ Alle 9 Aspekte abgedeckt (7 Rule-Types + Variants + Dependencies + Audit als Bonus).

"AI-Cost alle 3 Phasen"

  • Phase 1 (Sichtbarkeit): 10 Implementation-Steps, Token-Counter + Wrapper + Outbox + Worker + Aggregator + 2 Dashboards + Metrics + Doku ✓
  • Phase 2 (Schutz): 10 Implementation-Steps, Estimate + Assert + 402-Handling + Cron-Alerts + On-Demand-Trigger + Tenant-UI + Admin-Override + Doku ✓
  • Phase 3 (Monetarisierung): 10 Implementation-Steps, Markup + Overage-Mark + Nightly-Cron-Submit + Stripe-Docs + Period-UI + Audit + Reconcile + Tenant-Override + Doku ✓

Alle drei Phasen detailliert (15k+ Zeichen pro Datei), sequenziell mit klaren Übergaben.

"A für Marketing-Funnel + Email-Sequences + Self-Service-Conversion"

  • marketing-phase-1: Lead-Capture-API + Marketing-SDK + Admin-Inbox ✓
  • marketing-phase-2: Self-Service-Conversion + Attribution + Outbound-Webhooks ✓
  • marketing-phase-3: Email-Sequence-Engine + 4 Pre-Built Sequences + Statistics ✓

Alle drei User-Wünsche jeweils in eigener Phase abgedeckt.

"Form-Widget für Lead-Capture im CRM" — korrekt routed?

  • form-widget.md Implementation Step 6 (Z. 75-77): Worker-Handler routet je nach targetType:
    • form-submission → Generic-Row
    • crm-contact → upsert via existing CRM-Service mit Field-Mapping
    • entity-row → insert Row in Target-Entity ✓
  • Form-Builder-UI hat Field-Mapping-Builder bei crm-contact/entity-row (Z. 78) ✓
  • README.md Z. 39 listet form-widget als Block für marketing-funnel-phase-1: "Form-Widget liefert Patterns für Cross-Origin + Anti-Spam, die wiederverwendet werden" ✓

→ Routed.

"Hocuspocus Self-Hosted mit Graceful-Degradation"

→ Bereits in Section 3 ausführlich verifiziert. Architektur-Wahl, Container-Setup, Env-Disable, Container-Removal alle dokumentiert.


7. Security-Notes-Coverage

Self-loop MCP von Chatbot-V1/V2 → Capability-System

Nicht explizit in Phase-05-Files adressiert — gehört in Phase 07. Phase 05 liefert nur die Feature-Flag-Engine, die als "Capability-Gating" verwendet werden kann.

Finding SEC1 (Info): Self-loop-MCP-Schutz ist Phase-07-Konzern (chatbot-v1.md/chatbot-v2.md). Phase 05 erwähnt korrekterweise in feature-flags.md Blocks-Section: "06-plugin-system/hooks-lifecycle.md (#61) — Plugin-Capability-Gating" — Feature-Flag-Engine ist die Foundation. Kein explizites Self-loop-Issue zu adressieren in Phase 05.

Lead-Capture-Anti-Spam — Honeypot + Turnstile + Rate-Limit

marketing-funnel-phase-1.md Z. 130-135 + 56:

  • Honeypot ✓
  • Turnstile (opt-in via Flag) ✓
  • Rate-Limit (5/min/IP + 3/min/Email) ✓
  • IP-Logging dokumentiert + DSGVO-Doku-Update verwiesen ✓
  • Honeypot-Field-Name aus Env (HONEYPOT_FIELD_NAME) randomized — sehr nice ✓

→ Ausreichend.

Form-Submissions-CORS — strict whitelist

form-widget.md Z. 72 + 146-151:

  • Per-Form allowedOriginDomains String[] ✓
  • Origin-Header-Check im Submission-API ✓
  • Wildcard-Support (*.example.com) getestet ✓
  • Webhook-SSRF-Check (keine internen IPs) ✓
  • CSP-Header für iframe ✓

→ Strict.


8. Fehlende Aspekte (Lücken-Findings)

Finding L1 (Minor) — AI-Cost Provider-Pricing-Tables Update-Strategie

ai-cost-phase-1.md Z. 54-55 + 86-89: Pricing-Tables sind versioniert (pricing/v2026-05-16.ts) und im Repo-Commit (kein DB-Override). Security-Note Z. 140: "Pricing-Files im Repo-Commit, kein DB-Override → Audit-Trail über git-history."

Was fehlt: Update-Workflow ist nicht explizit dokumentiert. Wenn OpenAI z.B. am 1. Juni einen neuen Preis veröffentlicht, was ist der Operator-Workflow?

  • Wer triggert Pricing-Update?
  • Wie wird historische Cost-Migration für past-events gehandhabt (Z. 132: "neue Pricing-Datei mit Korrektur + Cron-Job zur Neuberechnung historischer Events (separater fix-Task)" — bleibt vage)?
  • Gibt es einen "Pricing-Drift-Detector" der bei großen Sprüngen warnt?

Empfehlung: In docs/features/ai-cost-billing.md (Phase-1-Doku, Z. 89) explizit einen "Pricing-Update-Runbook" hinzufügen. Beispiel-Sections:

  1. Wann updaten (monatlicher Provider-Doc-Check)
  2. Wie updaten (neue Pricing-File hinzufügen, alte nicht überschreiben)
  3. Backfill-Strategie (nur falls Pricing-Bug korrigiert; Provider-Preisänderung wirkt nur prospektiv)
  4. Tests für Pricing-File-Loading

Kein Blocker — kann während Step 10 (Doku) ergänzt werden.

Finding L2 (Minor) — Form-Widget iframe-Size-Negotiation via postMessage

form-widget.md Z. 67 erwähnt: "hört auf PostMessage toolctrl:form:resize für dynamic-height". Auch in Z. 127 als Acceptance-Criterion (toolctrl:form:resize funktional).

Was fehlt: Detailliertes Protokoll für iframe-Auto-Resize. Bei Form-Builder-Flexibilität (Felder werden hinzugefügt/entfernt, Conditional-Logic zeigt/versteckt Felder) kann iframe-Höhe stark variieren.

Empfehlung: Step 4 (Embedded-Form-App) sollte ResizeObserver auf Body verwenden + PostMessage mit { type: 'toolctrl:form:resize', height: number } an Parent emittieren. Step 3 (Loader) muss diesen Event empfangen und iframe.style.height = ...px setzen. Width sollte 100% bleiben (responsive).

Konkrete Spec-Ergänzung:

PostMessage-Protokoll:
- Child → Parent: { type: 'toolctrl:form:resize', height: number }
- Child → Parent: { type: 'toolctrl:form:submitted', leadId?: string, redirectUrl?: string }
- Child → Parent: { type: 'toolctrl:form:error', message: string }
- Parent → Child: { type: 'toolctrl:form:theme-update', themeJson: object } (optional)

Kann in Step 3+4 ergänzt werden; kein Blocker, aber implementer wird sonst raten.

Finding L3 (Minor) — Lessons Learned-Section optional aber nirgends gefüllt

Alle 9 Detail-MDs lassen Lessons Learned weg. Template Z. 128: "Lessons Learned (optional, am Ende des Tasks für nachfolgende Tasks)" → wird vom ausführenden Agent post-completion gefüllt. Keine Aktion nötig vor Execution.

Finding L4 (Info) — Phase-3 Cron-Trigger benötigt eigenen Trigger-Event-Pfad

marketing-funnel-phase-3.md Z. 78 erwähnt "Lost Lead Re-Activation" Trigger als "Cron-Job 60d-stale-leads scheint matching trigger". Implementation Step 11 (Z. 92-94) konkretisiert: Cron emit-Outbox-Event lead.stale_60d + tenant.trial_expiring.

Konsistenz-Prüfung: Step 2 (Z. 60) listet triggerEvent enum: lead.captured|lead.qualified|tenant.signup|tenant.trial_expiring|tenant.cancelled|custom. lead.stale_60d fehlt im Enum!

Empfehlung: Enum erweitern um lead.stale_60d oder als custom mit Custom-Trigger-Name behandeln. Andere Cron-emittierte Events ähnlich. Kann während Implementation korrigiert werden, aber sollte als Deviation festgehalten werden.

Finding L5 (Minor) — Form-Widget: File-Upload nicht in Phase 1

form-widget.md Security-Note Z. 147: "File-Upload (out-of-scope Phase 1): wenn File-Field später hinzukommt, dann AV-Scan-Layer aus Phase 01 Tasks #31/#32 einbinden."

→ Akzeptable Einschränkung. Klar als out-of-scope markiert. Field-Type-Liste in Step 2 (Z. 64) erwähnt file optional. Konsistent.

Finding L6 (Info) — Realtime-Collab Plan-Tier-Gating nicht detailliert

realtime-collab.md Depends Z. 25 erwähnt "Plan-Tier-Gating", aber Implementation-Steps spezifizieren keine konkrete Plan-Tier-Quota (z.B. "Free: keine Collab, Pro: 5 concurrent Collab-Editors, Enterprise: unlimited"). Security-Note Z. 137: "Limit per Tenant via Hocuspocus-onConnect-Hook prüft Concurrent-Connection-Count gegen Plan-Quota. Default 50/Tenant."

Empfehlung: Wäre wünschenswert, Plan-Tier-Quota in Entitlements-Schema (packages/entitlements/) wie in ai-cost-phase-2 zu definieren — z.B. collabConcurrentEditorsPerTenant. Kann während Implementation als Deviation ergänzt werden.


9. Phase-übergreifende Konsistenz

.env.example-Keys

README Done-Definition (Z. 81) listet: HOCUSPOCUS_URL, HOCUSPOCUS_SECRET, MARKETING_DOMAINS, FORM_WIDGET_CDN_URL, STRIPE_AI_OVERAGE_METER_ID (optional), TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY.

Cross-check pro File:

  • feature-flags.md: keine neuen Keys (Cache via SharedStore = existing Redis) — implicit, kein Issue
  • ai-cost-phase-1.md: keine Keys explizit — AI_COST_TRACKING_ENABLED in Rollback erwähnt aber nicht in .env.example-Step
  • ai-cost-phase-2.md: AI_QUOTA_ENFORCEMENT_ENABLED, AI_QUOTA_ALERTS_ENABLED in Rollback — nicht explizit ins .env.example aufgenommen
  • ai-cost-phase-3.md: STRIPE_AI_OVERAGE_METER_ID ✓ + AI_OVERAGE_SUBMISSION_ENABLED
  • form-widget.md: FORM_WIDGET_CDN_URL, TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY ✓ (Z. 129)
  • realtime-collab.md: HOCUSPOCUS_URL, HOCUSPOCUS_SECRET ✓ (Z. 116)
  • marketing-funnel-phase-1.md: MARKETING_DOMAINS, TURNSTILE_*, MARKETING_SDK_CDN_URL, HONEYPOT_FIELD_NAME ✓
  • marketing-funnel-phase-2.md: MARKETING_TOKEN_SECRET, LEAD_CONVERSION_ENABLED, MARKETING_WEBHOOKS_ENABLED ✓
  • marketing-funnel-phase-3.md: MARKETING_SEQUENCES_ENABLED (Rollback)

Finding ENV1 (Minor): Rollback-Killswitch-Env-Vars (AI_COST_TRACKING_ENABLED, AI_QUOTA_ENFORCEMENT_ENABLED, LEAD_CONVERSION_ENABLED, etc.) erscheinen nur in Rollback-Sections, sind aber nicht in .env.example-Acceptance-Criteria gelistet. Empfehlung: Per Detail-MD ein expliziter Acceptance-Criterion ".env.example enthält {alle Toggle-Keys}" hinzufügen — sonst werden sie vergessen.

Outbox-Event-Naming-Konsistenz

Verwendete Event-Namen über die Files:

  • ai-cost.persist-event (Phase 1/2/3)
  • ai-cost.aggregate-summary (Phase 1)
  • ai-quota.alert (Phase 2)
  • form.submission.process (Form-Widget)
  • marketing.lead.webhook (Marketing-Phase-2)
  • marketing.sequence.start / marketing.sequence.send (historical Marketing-Phase-3 spec names; current #80 docs use email-sequence-trigger / email-sequence-scheduler, with production send still deferred)
  • lead.captured, lead.qualified, lead.converted_to_trial, lead.converted_to_customer (Phase 2 → Phase 3)
  • lead.stale_60d, tenant.trial_expiring, tenant.signup, tenant.cancelled (Phase 3 Cron)

Naming-Pattern: {domain}.{entity}.{action} (kebab/dot) vs {entity}.{action} (für Lifecycle-Events).

Finding EVT1 (Info): Naming-Konvention nicht 100% einheitlich (z.B. ai-cost.persist-event mit dash vs ai-quota.alert mit dot vs lead.captured). Akzeptabel, da intuitiv lesbar — aber könnte in einem späteren Cleanup vereinheitlicht werden.


10a. 2026-05-27 Status-Reconciliation

This original verification report remains useful as a pre-execution spec audit, but several rows are now historical. Current status must be read from ../PROGRESS.md plus ../OPERATOR-CHECKLIST.md.

  • Marketing Funnel Phase 3 / #80 is still in_progress. The shipped surface is the data model, pure engine, four template definitions, scheduler foundation, tracking, unsubscribe, admin UI/CLI, live stats dashboard, and stale-lead/trial-expiring runner functions. It is not production marketing-sequence delivery until the delayed producer, sequence renderer, @toolctrl/mail adapter, seed data, stats aggregation cron, Playwright E2E, and production scheduled-job registration/deploy evidence land.
  • The canonical email-sequence status is docs/features/email-sequences.md. Use its model names (EmailSequence, EmailSequenceRun, EmailSequenceStepDelivery) and admin route (/admin/email-sequences) when reconciling stale references in this report or downstream plans.
  • The original "Lead-Capture -> ... -> erste Email versendet" expectation remains a future acceptance target, not current live proof. Current safe wording is: lead capture/conversion can create or display sequence state; production mail sending is deferred behind #80 follow-ups.

10. Zusammenfassung

Pass-Status

PASS. Alle 10 Files waren zum Zeitpunkt dieser historischen Planprüfung plan-quality-ready für Execution: Template-Konformität 100%, Dependencies konsistent, Implementation-Steps atomar und konkret genug für Subagent-Implementation, Test-Requirements präzise, Staging-Steps machbar. Das ist keine Aussage, dass Email-Sequences runtime-production-ready sind; der aktuelle Runtime-Status steht in docs/features/email-sequences.md.

Findings-Übersicht

ID Severity Datei Beschreibung
T1 Info alle Template-Konformität korrekt; Lessons-Learned optional weggelassen
D1 Info alle Dependencies konsistent
D2 Minor realtime-collab.md Blocks-Section dünn — akzeptabel
I1 Minor feature-flags.md Hash-Algo (SHA1) sollte in Step 2 explizit fixiert sein
I2 Info ai-cost-phase-1.md LLM-Pfad-Coverage vollständig
I3 Minor form-widget.md PostMessage-Resize-Protokoll nicht spezifiziert (siehe L2)
T2 Info alle Test-Sections konsistent qualitativ hochwertig
S1 Info 3 Files Staging-Steps für externe Assets vollständig
SEC1 Info feature-flags.md Self-loop-MCP-Schutz korrekt nach Phase 07 verschoben
L1 Minor ai-cost-phase-1.md Pricing-Update-Runbook fehlt explizit
L2 Minor form-widget.md iframe-Resize-PostMessage-Protokoll konkretisieren
L3 Info alle Lessons Learned post-Execution füllen
L4 Minor marketing-funnel-phase-3.md lead.stale_60d fehlt im triggerEvent-Enum
L5 Info form-widget.md File-Upload explizit out-of-scope (OK)
L6 Info realtime-collab.md Plan-Tier-Quota Detail wünschenswert
ENV1 Minor mehrere Rollback-Killswitch-Env-Vars nicht in Acceptance-Criteria gelistet
EVT1 Info mehrere Outbox-Event-Naming nicht 100% einheitlich (akzeptabel)

Konkrete Empfehlungen vor Execution-Start

  1. L4 (Pflicht): marketing-funnel-phase-3.md Z. 60 — Enum-Erweiterung um lead.stale_60d (oder Cron-Trigger-Custom-Variante explizit definieren) — sonst Mismatch zwischen Step 2 und Step 11.
  2. L2 (Empfohlen): form-widget.md Step 3+4 — PostMessage-Protokoll-Detail spezifizieren (4 Message-Types).
  3. ENV1 (Empfohlen): Detail-MDs um zusätzlichen Acceptance-Criterion ".env.example enthält alle Killswitch-Env-Vars" ergänzen.
  4. L1 (Empfohlen): ai-cost-phase-1.md Step 10 (Doku) — explizit "Pricing-Update-Runbook" als Pflicht-Section.
  5. I1 (Optional): feature-flags.md Step 2 — Hash-Algo (SHA-256 empfohlen) explizit fixieren.

Alle anderen Findings sind Info-Level oder können während Implementation als Deviations dokumentiert werden.

Bereitschaftserklärung

Phase 05 ist executable. Subagents können auf Basis der Spec ohne weitere Architektur-Entscheidungen implementieren. Vor allem die Cross-File-Konsistenz (Dependencies, README-Done-Definition, Track-Aufteilung) ist sauber. Die ~16 Findings sind allesamt iterativ während der Execution behebbar — keine architectural redesigns nötig.