feat(pipeline): 9→7 stage refactor + v1.1 hardening wave

Replaces the legacy 9-stage pipeline with 7 canonical stages
(enquiry → qualified → eoi → reservation → deposit_paid → contract →
nurturing) plus three doc sub-status columns (eoi_doc_status,
reservation_doc_status, contract_doc_status) that track sent/signed
within a single stage instead of branching it.

Schema (migration 0062):
- interests gains assigned_to, deposit_expected_amount/currency,
  three doc-status columns, two documenso-id columns, and
  date_reservation_signed.
- New tables: qualification_criteria (per-port admin-configurable),
  interest_qualifications (per-interest state), payments (deposit /
  balance / refund records keyed to interest + client).
- Default qualification criteria seeded for every existing port.
- Dummy-data UPDATEs collapse Sent/Signed pairs and 'completed' into
  the new stage + doc-status + outcome shape.

Migration 0063 adds interest_contact_log.voice_transcript and
template_used columns for v1.1-A/B (quick-template buttons + voice
transcription via Web Speech API).

v1.1 phase work bundled here:
- A/B: Quick-template buttons (Call / Visit / Email) + mic toggle on
       the contact-log compose dialog (useVoiceTranscription hook).
- C:   berth-rules-engine wraps state writes in pg_advisory_xact_lock
       with an idempotent re-read; emits rule_evaluated audit traces.
- D:   Documenso webhook: reservation/contract sub-status stamping
       moved out of the PDF-download try-block so a download failure
       no longer swallows the stamp. New integration test coverage.
- E:   /admin/qualification-criteria CRUD page + admin component.
- F:   default_new_interest_owner exposed in System Settings.
- G:   recentActivityCount + active_engagement deal-pulse signal
       surfaced as a chip on interests + hot-deals card.
- H:   interest_assigned notification on assignedTo change (skips
       self-assign, uses a dedupe key).

Plus the supporting components: AssignedToChip, DealPulseChip,
PaymentsSection, QualificationChecklist, MultiEoiChip,
SkipAheadBanner, WonStatusPanel, InterestBerthStatusBanner,
SupplementalInfoRequestButton, UserPicker.

Tests: 1370/1370 vitest pass (added deal-health unit suite +
expanded constants/validators/pipeline-transitions coverage). tsc
clean, eslint clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/app/(dashboard)/[portSlug]/admin/ai/page.tsx

@@ -1,5 +1,5 @@
 import Link from 'next/link';
-import { Bot, Receipt, FileText, Brain, ExternalLink } from 'lucide-react';
+import { Bot, FileText, Brain, ExternalLink } from 'lucide-react';
 
 import {
   SettingsFormCard,
@@ -7,6 +7,7 @@ import {
 } from '@/components/admin/shared/settings-form-card';
 import { PageHeader } from '@/components/shared/page-header';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { OcrSettingsForm } from '@/components/admin/ocr-settings-form';
 
 const MASTER_FIELDS: SettingFieldDef[] = [
   {
@@ -59,13 +60,6 @@ interface FeatureLink {
 }
 
 const FEATURE_LINKS: FeatureLink[] = [
-  {
-    href: '../ocr',
-    icon: Receipt,
-    title: 'Receipt OCR settings',
-    description:
-      'Provider, model, and confidence thresholds for the receipt scanner. AI fallback only runs when the on-device parser is uncertain.',
-  },
   {
     href: '../berth-pdf-parser',
     icon: FileText,
@@ -103,6 +97,21 @@ export default function AiAdminPage() {
         fields={PROVIDER_FIELDS}
       />
 
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base flex items-center gap-2">
+            <Bot className="h-4 w-4" /> Receipt OCR
+          </CardTitle>
+          <CardDescription>
+            Provider, model, and confidence thresholds for the receipt scanner. AI fallback only
+            runs when the on-device parser is uncertain.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <OcrSettingsForm embedded />
+        </CardContent>
+      </Card>
+
       <Card>
         <CardHeader>
           <CardTitle className="text-base flex items-center gap-2">

src/app/(dashboard)/[portSlug]/admin/qualification-criteria/page.tsx

@@ -0,0 +1,15 @@
+import { QualificationCriteriaAdmin } from '@/components/admin/qualification-criteria-admin';
+import { PageHeader } from '@/components/shared/page-header';
+
+export default function QualificationCriteriaPage() {
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Qualification criteria"
+        eyebrow="ADMIN"
+        description="Configure the checklist reps complete before a deal moves out of the Enquiry stage. Reorder, enable/disable, or add port-specific criteria. The 'fully qualified' hint on the interest detail surfaces when every enabled criterion is confirmed."
+      />
+      <QualificationCriteriaAdmin />
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/expenses/page.tsx

@@ -1,9 +1,9 @@
 'use client';
 
-import { useState } from 'react';
+import { useMemo, useState } from 'react';
 import { useParams } from 'next/navigation';
 import { Plus, Download, FileText, FileSpreadsheet } from 'lucide-react';
-import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 
 import { Button } from '@/components/ui/button';
 import {
@@ -21,7 +21,7 @@ import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog
 import { PermissionGate } from '@/components/shared/permission-gate';
 import { ExpenseFormDialog } from '@/components/expenses/expense-form-dialog';
 import { ExpenseCard } from '@/components/expenses/expense-card';
-import { expenseFilterDefinitions } from '@/components/expenses/expense-filters';
+import { buildExpenseFilterDefinitions } from '@/components/expenses/expense-filters';
 import { getExpenseColumns, type ExpenseRow } from '@/components/expenses/expense-columns';
 import { useCreateFromUrl } from '@/hooks/use-create-from-url';
 import { usePaginatedQuery } from '@/hooks/use-paginated-query';
@@ -33,6 +33,18 @@ export default function ExpensesPage() {
   const portSlug = params?.portSlug ?? '';
   const queryClient = useQueryClient();
 
+  // Per-port category override. Falls back to shipped defaults until the
+  // vocab call resolves, so the filter bar always renders something.
+  const { data: vocab } = useQuery<{ data: Record<string, readonly string[]> }>({
+    queryKey: ['vocabularies'],
+    queryFn: () => apiFetch('/api/v1/vocabularies'),
+    staleTime: 5 * 60_000,
+  });
+  const filterDefs = useMemo(
+    () => buildExpenseFilterDefinitions(vocab?.data?.expense_categories),
+    [vocab],
+  );
+
   const [createOpen, setCreateOpen] = useState(false);
   useCreateFromUrl(() => setCreateOpen(true));
   const [editExpense, setEditExpense] = useState<ExpenseRow | null>(null);
@@ -53,7 +65,7 @@ export default function ExpensesPage() {
   } = usePaginatedQuery<ExpenseRow>({
     queryKey: ['expenses'],
     endpoint: '/api/v1/expenses',
-    filterDefinitions: expenseFilterDefinitions,
+    filterDefinitions: filterDefs,
   });
 
   useRealtimeInvalidation({
@@ -132,7 +144,7 @@ export default function ExpensesPage() {
       />
 
       <FilterBar
-        filters={expenseFilterDefinitions}
+        filters={filterDefs}
         values={filters}
         onChange={setFilter}
         onClear={clearFilters}

src/app/(portal)/portal/interests/page.tsx

@@ -36,15 +36,13 @@ function portalSigningLabel(status: string): string {
 }
 
 const STAGE_VARIANT: Record<PipelineStage, 'default' | 'secondary' | 'destructive' | 'outline'> = {
-  open: 'secondary',
-  details_sent: 'secondary',
-  in_communication: 'default',
-  eoi_sent: 'default',
-  eoi_signed: 'default',
-  deposit_10pct: 'default',
-  contract_sent: 'default',
-  contract_signed: 'default',
-  completed: 'outline',
+  enquiry: 'secondary',
+  qualified: 'secondary',
+  nurturing: 'secondary',
+  eoi: 'default',
+  reservation: 'default',
+  deposit_paid: 'default',
+  contract: 'outline',
 };
 
 export default async function PortalInterestsPage() {

src/app/api/v1/admin/qualification-criteria/[id]/route.ts

@@ -0,0 +1,40 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { updateQualificationCriterionSchema } from '@/lib/validators/qualification';
+import { deleteCriterion, updateCriterion } from '@/lib/services/qualification.service';
+
+export const PATCH = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, updateQualificationCriterionSchema);
+      const row = await updateCriterion(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: row });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('admin', 'manage_settings', async (_req, ctx, params) => {
+    try {
+      await deleteCriterion(params.id!, ctx.portId, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return new NextResponse(null, { status: 204 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/qualification-criteria/route.ts

@@ -0,0 +1,33 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { createQualificationCriterionSchema } from '@/lib/validators/qualification';
+import { createCriterion, listCriteriaForPort } from '@/lib/services/qualification.service';
+
+export const GET = withAuth(async (_req, ctx) => {
+  try {
+    const data = await listCriteriaForPort(ctx.portId);
+    return NextResponse.json({ data });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+
+export const POST = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx) => {
+    try {
+      const body = await parseBody(req, createQualificationCriterionSchema);
+      const row = await createCriterion(ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: row }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/contact-log/[id]/route.ts

@@ -15,6 +15,8 @@ export const PATCH = withAuth(
         channel: body.channel,
         direction: body.direction,
         summary: body.summary,
+        voiceTranscript: body.voiceTranscript,
+        templateUsed: body.templateUsed,
         followUpAt: body.followUpAt,
       });
       return NextResponse.json({ data: entry });

src/app/api/v1/interests/[id]/contact-log/route.ts

@@ -27,6 +27,8 @@ export const POST = withAuth(
         channel: body.channel,
         direction: body.direction,
         summary: body.summary,
+        voiceTranscript: body.voiceTranscript ?? null,
+        templateUsed: body.templateUsed ?? null,
         followUpAt: body.followUpAt ?? null,
       });
       return NextResponse.json({ data: entry }, { status: 201 });

src/app/api/v1/interests/[id]/payments/route.ts

@@ -0,0 +1,51 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { createPaymentSchema } from '@/lib/validators/payments';
+import {
+  createPayment,
+  getDepositTotalForInterest,
+  listPaymentsForInterest,
+} from '@/lib/services/payments.service';
+
+export const GET = withAuth(
+  withPermission('interests', 'view', async (_req, ctx, params) => {
+    try {
+      const interestId = params.id!;
+      const [payments, depositTotal] = await Promise.all([
+        listPaymentsForInterest(interestId, ctx.portId),
+        getDepositTotalForInterest(interestId, ctx.portId),
+      ]);
+      return NextResponse.json({ data: { payments, depositTotal } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('invoices', 'record_payment', async (req, ctx, params) => {
+    try {
+      // Body's interestId must match the URL param — defense-in-depth against
+      // a client that sends one ID in the URL but another in the body.
+      const body = await parseBody(req, createPaymentSchema);
+      if (body.interestId !== params.id) {
+        return NextResponse.json(
+          { error: 'interestId in body must match URL parameter' },
+          { status: 400 },
+        );
+      }
+      const payment = await createPayment(ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: payment }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/interests/[id]/qualifications/route.ts

@@ -0,0 +1,44 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { setInterestQualificationSchema } from '@/lib/validators/qualification';
+import {
+  isInterestFullyQualified,
+  listInterestQualifications,
+  setInterestQualification,
+} from '@/lib/services/qualification.service';
+
+export const GET = withAuth(
+  withPermission('interests', 'view', async (_req, ctx, params) => {
+    try {
+      const interestId = params.id!;
+      const [criteria, fullyQualified] = await Promise.all([
+        listInterestQualifications(interestId, ctx.portId),
+        isInterestFullyQualified(interestId, ctx.portId),
+      ]);
+      return NextResponse.json({ data: { criteria, fullyQualified } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const PUT = withAuth(
+  withPermission('interests', 'edit', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, setInterestQualificationSchema);
+      const criteria = await setInterestQualification(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      const fullyQualified = criteria.every((c) => c.confirmed);
+      return NextResponse.json({ data: { criteria, fullyQualified } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/payments/[id]/route.ts

@@ -0,0 +1,40 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { updatePaymentSchema } from '@/lib/validators/payments';
+import { deletePayment, updatePayment } from '@/lib/services/payments.service';
+
+export const PATCH = withAuth(
+  withPermission('invoices', 'record_payment', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, updatePaymentSchema);
+      const payment = await updatePayment(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: payment });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('invoices', 'record_payment', async (_req, ctx, params) => {
+    try {
+      await deletePayment(params.id!, ctx.portId, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return new NextResponse(null, { status: 204 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);