feat(gtm): Spec 1E — qualified lead + drift guard (analytics-foundation 1e) (#376)

* docs(gtm): spec for analytics-foundation-1e (qualified lead + drift guard)

Closes analytics-foundation. Two deliverables carved out of Spec 1D:
- marketing:lead_qualified server-side, fired from /api/leads when the
  enterprise gate passes (non-personal email domain + non-empty company).
  Personal-email blocklist lives in @ngaf/telemetry/shared.
- Code → taxonomy drift guard (mirror of the existing insights guard).
  Regex scanner over apps/ + libs/ asserts every fired event name is
  documented in docs/gtm/taxonomy.md.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* docs(gtm): implementation plan for analytics-foundation-1e (qualified lead + drift guard)

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* feat(telemetry): add PERSONAL_EMAIL_DOMAINS + isPersonalEmailDomain

19 free-mail domains in a ReadonlySet plus a case-insensitive predicate.
Used by the website's lead-qualification gate to filter out personal
email submissions before firing marketing:lead_qualified.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* feat(telemetry): export isPersonalEmailDomain from @ngaf/telemetry/shared

Both the website (lead-qualification gate, this PR) and any future
consumer can import the blocklist + predicate from the published lib.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* feat(website): add marketingLeadQualified to analyticsEvents map

Symbolic ref for the new server-side event. Wiring lands in Tasks 1.2
and 1.3.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* feat(website): fire marketing:lead_qualified server-side on enterprise leads

captureLeadQualified gates on getEmailDomain(email) being present,
isPersonalEmailDomain(domain) being false, and toSafeAnalyticsString(company, 200)
being non-empty. When all three pass, fires marketing:lead_qualified with
properties { email_domain, company, source_page, track: 'enterprise' }.

Wired from /api/leads/route.ts immediately after captureLeadConversion.
Five unit tests cover the gate matrix.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* test(posthog): drift guard for code → taxonomy

New node:test script that scans apps/ + libs/ for event-name literals
fired via posthog.capture(...), track(...), captureServerEvent({event}),
or analyticsEvents.<key>. Asserts every name is documented in
docs/gtm/taxonomy.md. Mirror of the existing insights → taxonomy guard.

Catches the kind of drift that slipped through during Spec 1C
(cockpit:recipe_start → recipe_opened rename).

Co-Authored-By: Claude Opus 4.7 <[email protected]>

---------

Co-authored-by: Claude Opus 4.7 <[email protected]>

Author: blove

apps/website/src/app/api/leads/route.ts

@@ -4,7 +4,7 @@ import path from 'path';
 import { sendEmail, FROM, NOTIFY_TO, addToAudience } from '../../../../lib/resend';
 import { loopsUpsertContact, loopsSendEvent } from '../../../../lib/loops';
 import { leadNotificationHtml } from '../../../../emails/lead-notification';
-import { captureLeadConversion } from '../../../lib/analytics/server';
+import { captureLeadConversion, captureLeadQualified } from '../../../lib/analytics/server';
 import { getSourcePage } from '@ngaf/telemetry/shared';
 
 const LEADS_FILE = path.join(process.cwd(), 'data', 'leads.ndjson');
@@ -61,6 +61,7 @@ export async function POST(req: NextRequest) {
   }
 
   await captureLeadConversion({ email, company, sourcePage });
+  await captureLeadQualified({ email, company, sourcePage });
 
   return NextResponse.json({ ok: true });
 }

apps/website/src/lib/analytics/events.ts

@@ -8,6 +8,7 @@ export const analyticsEvents = {
   marketingLeadFormSubmit: 'marketing:lead_form_submit',
   marketingLeadFormSuccess: 'marketing:lead_form_success',
   marketingLeadFormFail: 'marketing:lead_form_fail',
+  marketingLeadQualified: 'marketing:lead_qualified',
   marketingNewsletterSignupSubmit: 'marketing:newsletter_signup_submit',
   marketingNewsletterSignupSuccess: 'marketing:newsletter_signup_success',
   marketingNewsletterSignupFail: 'marketing:newsletter_signup_fail',

apps/website/src/lib/analytics/server.spec.ts

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: MIT
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+const captureMock = vi.hoisted(() => vi.fn());
+vi.mock('posthog-node', () => ({
+  PostHog: vi.fn(function () {
+    return {
+      capture: captureMock,
+      shutdown: vi.fn().mockResolvedValue(undefined),
+    };
+  }),
+}));
+
+beforeEach(() => {
+  captureMock.mockClear();
+  process.env.NEXT_PUBLIC_POSTHOG_TOKEN = 'phc_test';
+});
+
+describe('captureLeadQualified', () => {
+  it('fires marketing:lead_qualified when domain is non-personal and company is non-empty', async () => {
+    const { captureLeadQualified } = await import('./server');
+    await captureLeadQualified({
+      email: '[email protected]',
+      company: 'Acme',
+      sourcePage: '/pricing',
+    });
+    expect(captureMock).toHaveBeenCalledTimes(1);
+    const call = captureMock.mock.calls[0][0];
+    expect(call.event).toBe('marketing:lead_qualified');
+    expect(call.properties).toMatchObject({
+      email_domain: 'acme.com',
+      company: 'Acme',
+      source_page: '/pricing',
+      track: 'enterprise',
+    });
+    expect(call.distinctId).toMatch(/^email_sha256:[a-f0-9]{64}$/);
+  });
+
+  it('skips when the email domain is personal', async () => {
+    const { captureLeadQualified } = await import('./server');
+    await captureLeadQualified({
+      email: '[email protected]',
+      company: 'Acme',
+      sourcePage: '/pricing',
+    });
+    expect(captureMock).not.toHaveBeenCalled();
+  });
+
+  it('skips when company is missing', async () => {
+    const { captureLeadQualified } = await import('./server');
+    await captureLeadQualified({
+      email: '[email protected]',
+      sourcePage: '/pricing',
+    });
+    expect(captureMock).not.toHaveBeenCalled();
+  });
+
+  it('skips when company is blank string', async () => {
+    const { captureLeadQualified } = await import('./server');
+    await captureLeadQualified({
+      email: '[email protected]',
+      company: '   ',
+      sourcePage: '/pricing',
+    });
+    expect(captureMock).not.toHaveBeenCalled();
+  });
+
+  it('skips when email is malformed', async () => {
+    const { captureLeadQualified } = await import('./server');
+    await captureLeadQualified({
+      email: 'not-an-email',
+      company: 'Acme',
+    });
+    expect(captureMock).not.toHaveBeenCalled();
+  });
+});

apps/website/src/lib/analytics/server.ts

@@ -1,7 +1,7 @@
 import { createHash } from 'crypto';
 import { PostHog } from 'posthog-node';
 import { analyticsEvents, type AnalyticsEventName, type AnalyticsProperties, type WhitepaperId } from './events';
-import { getEmailDomain, normalizePostHogHost, toSafeAnalyticsString } from '@ngaf/telemetry/shared';
+import { getEmailDomain, isPersonalEmailDomain, normalizePostHogHost, toSafeAnalyticsString } from '@ngaf/telemetry/shared';
 
 function getServerPostHogClient(): PostHog | null {
   const token = toSafeAnalyticsString(process.env.NEXT_PUBLIC_POSTHOG_TOKEN, 500);
@@ -73,6 +73,36 @@ export async function captureLeadConversion({
   });
 }
 
+export async function captureLeadQualified({
+  email,
+  company,
+  sourcePage,
+}: {
+  email: string;
+  company?: string;
+  sourcePage?: string;
+}) {
+  const domain = getEmailDomain(email);
+  if (!domain || isPersonalEmailDomain(domain)) return;
+
+  const safeCompany = toSafeAnalyticsString(company, 200);
+  if (!safeCompany) return;
+
+  const distinctId = getHashedEmailDistinctId(email);
+  if (!distinctId) return;
+
+  await captureServerEvent({
+    distinctId,
+    event: analyticsEvents.marketingLeadQualified,
+    properties: {
+      email_domain: domain,
+      company: safeCompany,
+      source_page: sourcePage,
+      track: 'enterprise',
+    },
+  });
+}
+
 export async function captureWhitepaperConversion({
   email,
   paper,