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

472 lines
29 KiB
Markdown

# 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.