[Phase 9] Epic — Full CRM Depth & Relationship Graph #604

Umbrella epic for Phase 9 — Full CRM Depth & Relationship Graph of the SiteStacker parity program. Full context: docs/prds/sitestacker-parity/phase-09-full-crm-depth-relationship-graph.md — the single source of truth (§A architecture rulings, §B deep modules, §C predecessor amendments, §D data model, §E contracts & wiring, §F ADRs, Testing Decisions, Evidence & Acceptance, Tracking Issues). All twenty children below cite that PRD; when an issue body and the PRD disagree, the PRD wins.

Mission

Modern SiteStacker parity — and the missions-CRM depth beyond it — for the operational heart of the platform: a real party model (people, churches, organizations, households), a real relationship graph (stored + derived edges with provenance), and a real record surface (one list engine, one record shell, one timeline) so that staff can open a person, church, organization, or household and see a complete operational record without jumping to donor-specific pages or spreadsheets — and no legacy donor grid, drawer, or detail routes remain. The north star (founder-ratified, PRD D3) is the best nonprofit CRM for Christian Missions organizations: support-raising, sending churches, staff assignment, and mobilization seams over generic-donor-CRM parity. This is a fresh-build replacement phase (D6: no users exist; no continuity ceremony), built directly on Asym Postgres (ADR-0001: Twenty retired), inheriting Phase 4 tenant-isolation plumbing and the Phase 7 party spine as amended 2026-07-06 (PRD §C2).

What to build

One coherent CRM depth layer — party spine → relationship graph → record shell → list engine → search → writes — replacing the legacy donor surface outright. The ten moving parts (each owned end-to-end by the children below):

1. Party spine (§A1–A3). Thin parties supertype with shared-PK subtyping: persons.id = parties.id (same for household and org subtype rows); party_kind ∈ {person, household, org} with 'group' reserved-not-built; churches are org-kind parties with org_type='church'. donors.party_id ships NOT NULL with a composite tenant FK from the first migration; donors.party_type is never created; donors.missionary_id, donors.type, donors.organization, donors.spouse, the donors.notes scalar, and donor_activities die.
2. Hybrid relationship graph (§A4–A6). crm_relationships is ONE canonical edge per relationship (never mirrored pairs), typed by a seeded crm_relationship_types catalog (24 launch types dispositioned in §D), time-bound and never hard-deleted. Derived edges (supports-from-ledger, household membership, org contacts) are security_invoker SQL views, never persisted, merged with stored edges in one UNION ALL surface carrying provenance and keyset pagination. "Supports" is the named, versioned supports_policy_v1.
3. Derived roles, never authorization (§A7). Donor/missionary/board/volunteer/staff/partner are derived display roles from the ledger, records, and edges; authz.memberships stays the sole authorization source, enforced by a CI import gate plus a runtime negative test.
4. One record shell for every kind (§A10–A12). A header contract (consent badges + per-address deliverability, lifecycle-status chip, duplicate-warning banner, portal/claim chip, owner chip reading assignment edges with N role-qualified assignees + ONE primary, tags, privacy indicator, reserved action-slot registry) + eight live tabs (Overview, Contact, Relationships, Giving incl. Commitments + the payment-instruments read panel, Notes, Activity, Tasks thin, Audit thin/permission-gated) + eight hidden registry sockets (Communications P6, Custom Fields P11, Files P29, Workflow coordination P34 + application/mobilization source P41, Events participation P37, Payment-Methods staff actions, External IDs / provider links P30, Donor Development / Portfolio P27) — rendered by one layout-agnostic component in both the peek drawer and the full page.
5. One list engine, kind routes as pinned views (§A13–A14). /crm + /crm/people + /crm/churches + /crm/organizations + /crm/households + work queues /crm/relationships, /crm/duplicates, /crm/tasks — one engine. Saved views are first-class live-query rows (private-only at launch; team/everyone reserved); the filter schema is nested AND/OR from day one; the URL is the source of truth for view+filter+sort+cursor; pagination is keyset-only with rebuilt parameterized predicates (deleting escapeSearchValue and the comma-mutation); a server facet-options endpoint; semantic-table a11y with DataTableResponsive as the only grid primitive; Next.js 16 layout + Suspense + canonical detail pages with intercepting @drawer routes replacing the ?donor= state machine.
6. Cmd-K global search (§A15). A pg_trgm GIN UNION ALL surface (parties display-name + donors email/phone), grouped by kind with recents, permission-bound to the same scope as the detail/list read models, replacing the hardcoded fake SearchDialog.
7. Party-keyed engagement replaces donor-keyed outright (§A16, §D). crm_notes (Tiptap JSON + plain text; standard/restricted visibility), crm_activity_events (seeded taxonomy), flat tags on the party spine, and a 'party' task-link record type; the timeline is always composed at read from source-truth branches — never persisted.
8. Plain Asym writes (§A17). Every mutation: authz capability check → zod validation → withTenant → ONE transaction containing (a) the row write, (b) a crm_audit_events row, (c) the crm_activity_events emission. No fail-closed provider gate, no provider-idempotency log, no crm_write_gates dependency — ADR-0001 §4 withdrew the gate and Phase 9 must not invent one.
9. Governed CSV export (§A18). A minimal list CSV export through Phase 3 export governance (csvSafeCell + consent gate + audit), honoring field policies.
10. Fresh-build discipline (D6, §E4). The legacy donor grid, drawer, ?donor= machinery, and monolithic detail service are deleted; the cursor envelope, virtualization, named-views storage, and the CRM Inline Operation Parity #270 operation shell are reused on merit; seeds regenerate correct-from-start including synthetic duplicate pairs, ≥1 merged tombstone per kind, and staff-assignment edges — else the dedupe queue, merge workbench, duplicate banner, and owner chips are undemonstrable in fresh environments.

Hard invariants (bind every child)

• Tenant isolation: composite (tenant_id, id) keys, ENABLE+FORCE RLS, withTenant tenant-guard, cross-tenant negative CI tier — inherited from Phase 4, never re-invented.
• Single canonical edge, never mirrored — mirrored relationship pairs are a forbidden topology.
• Derived kinds are structurally blocked from the stored catalog (CHECK + API rejection + test); relationship types are never hard-coded in an app page (catalog edited via migrations/seed only until the Phase 11/12 catalog UI).
• Derived roles are display-only, never authorization (CI dependency gate: the authz package cannot import the roles view; plus a runtime negative test).
• Provenance-scoped permissions: giving-derived edges and giving context inherit FINANCE visibility; anonymity is respected; both negative-tested.
• Member-care exclusion: member_care_private_notes stays RLS-revoked; the composed timeline references no member_care% relation (CI assertion); only the permission-gated Overview indicator references care.
• Staff NEVER key card data into any surface this platform renders — read-only Stripe PaymentMethods metadata only; updates complete via donor secure links (§A11; SAQ-A intact). No admin-app card form, ever.
• Cultivation stage is NEVER a lifecycleStatus value; asks are never edges or custom fields (§A12 Phase 27 guardrails).

Children

• [Phase 9] Docs foundation: party-topology ADR, OpenSpec delta, glossary + matrix discipline #605 — Docs foundation: the F1 ADR ("Party-model topology for CRM depth"), OpenSpec delta, CONTEXT.md glossary verification, parity-matrix row discipline. (foundation; unblocked)
• [Phase 9] Extend the party spine: lifecycle_status, tags, merge tombstone; regenerate seeds #606 — Party-spine additions on the Phase-7-T4-built spine: lifecycle_status + tags + merged_into_party_id; never-created/dropped column dispositions; seed regeneration incl. synthetic duplicates, merged tombstones, staff-assignment edges. (hard prereq: [Phase 4] 🗺️ Epic — Identity & Account-Claiming Foundation #503 + [Phase 7] Party spine: parties supertype + persons anchor + households + household_members + org subtype + org_contacts + donors.party_id #570)
• [Phase 9] Build the stored relationship graph: crm_relationships + seeded type catalog #607 — Stored relationship graph: crm_relationships + crm_relationship_types + catalog seed per the §D disposition table + B2 edge service. (blocked on [Phase 9] Extend the party spine: lifecycle_status, tags, merge tombstone; regenerate seeds #606)
• [Phase 9] Build derived-edge views + the provenance UNION graph surface (supports_policy_v1) #608 — Derived-edge views + the provenance UNION graph surface + supports_policy_v1. (blocked on [Phase 9] Build the stored relationship graph: crm_relationships + seeded type catalog #607)
• [Phase 9] Derived-roles view: frozen contract, display-only, never authorization + D3 gates #609 — Derived-roles view + the D3 enforcement tiers (authz import gate, schema-shape test, no-new-inline-contact-columns migration lint). (blocked on [Phase 9] Build the stored relationship graph: crm_relationships + seeded type catalog #607)
• [Phase 9] Merge membership — join parties, edges & engagement to the Phase 4 A9 re-point #610 — Merge membership: parties, edges & engagement tables join the Phase 4 A9 re-point contract (extends [Phase 4] Non-destructive merge execution (golden record, tombstone, replayable, un-merge) #512/[Phase 4] Merge UI (dedupe queue + CRM-search multi-select → golden-record compare sheet) #514, never forks). (blocked on [Phase 9] Extend the party spine: lifecycle_status, tags, merge tombstone; regenerate seeds #606, [Phase 9] Build the stored relationship graph: crm_relationships + seeded type catalog #607, [Phase 9] Build party-keyed Notes: crm_notes schema, service, Notes tab, visibility gate #616, [Phase 9] Build the activity timeline: crm_activity_events + composed UNION read #617, [Phase 9] Integrate tasks with parties: 'party' task links, read service, Tasks tab + queue #618, [Phase 9] Build the CRM write path + audit: transactional command core, Audit tab + socket #620; hard prereq: [Phase 4] 🗺️ Epic — Identity & Account-Claiming Foundation #503)
• [Phase 9] Build the list-engine core + saved views: predicates, cursor, URL-as-state, facets #611 — List-engine core + saved views: parameterized predicates, cursor-envelope rebuild, facet endpoint, count budgets, virtualization fixes, first-class live saved views, URL-as-state, generalized named-views payload. (blocked on [Phase 9] Extend the party spine: lifecycle_status, tags, merge tombstone; regenerate seeds #606)
• [Phase 9] Build /crm kind routes + navigation: layout chrome, pinned system views, queues #612 — Routes + Next.js 16 architecture: /crm layout chrome, kind routes as pinned system views, /crm/tasks queue slot, nav registration. (blocked on [Phase 9] Build the list-engine core + saved views: predicates, cursor, URL-as-state, facets #611)
• [Phase 9] Build the record shell: D4 header contract, tab registry, @drawer peek routes #613 — Record shell: D4 header contract + tab registry + the eight hidden sockets + reserved action slots + canonical detail pages with @drawer interception. (blocked on [Phase 9] Build /crm kind routes + navigation: layout chrome, pinned system views, queues #612)
• [Phase 9] Build Overview + Contact tabs: family, support-vs-goal, consent & suppression #614 — Overview + Contact tabs: family panel, support-vs-goal widget, key-contacts strip, labeled donors.score, consent & communication-preferences section, per-address suppression status. (blocked on [Phase 9] Build the record shell: D4 header contract, tab registry, @drawer peek routes #613)
• [Phase 9] Build the Giving tab: operation-shell carryover, Commitments, payment instruments #615 — Giving tab: CRM Inline Operation Parity #270 operation-shell carryover + Commitments + payment-instruments read panel + the four reserved columns + the "request payment update" action socket. (blocked on [Phase 9] Build the record shell: D4 header contract, tab registry, @drawer peek routes #613)
• [Phase 9] Build party-keyed Notes: crm_notes schema, service, Notes tab, visibility gate #616 — Party-keyed Notes: crm_notes (§D exact columns), B8 service, Notes tab, visibility gate. (blocked on [Phase 9] Build the record shell: D4 header contract, tab registry, @drawer peek routes #613)
• [Phase 9] Build the activity timeline: crm_activity_events + composed UNION read #617 — Activity timeline: crm_activity_events + taxonomy seed + the composed UNION timeline + member-care exclusion. (blocked on [Phase 9] Build the record shell: D4 header contract, tab registry, @drawer peek routes #613, [Phase 9] Build party-keyed Notes: crm_notes schema, service, Notes tab, visibility gate #616)
• [Phase 9] Integrate tasks with parties: 'party' task links, read service, Tasks tab + queue #618 — Tasks: 'party' task links + reverse index + tasks-for-party service + Tasks tab + /crm/tasks work queue. (blocked on [Phase 9] Build the record shell: D4 header contract, tab registry, @drawer peek routes #613)
• [Phase 9] Build Cmd-K global search: pg_trgm UNION surface + permission-bound endpoint #619 — Cmd-K search: pg_trgm + the UNION search surface + permission-bound endpoint; replaces the demo SearchDialog. (blocked on [Phase 9] Extend the party spine: lifecycle_status, tags, merge tombstone; regenerate seeds #606)
• [Phase 9] Build the CRM write path + audit: transactional command core, Audit tab + socket #620 — Write path + Audit: crm_audit_events, the A17 transactional command core, the Audit tab + Phase 8 ops-indicator socket. (blocked on [Phase 9] Extend the party spine: lifecycle_status, tags, merge tombstone; regenerate seeds #606)
• [Phase 9] Ship governed CSV list export through Phase 3 export governance #621 — Governed CSV export through Phase 3 export governance. (blocked on [Phase 9] Build the list-engine core + saved views: predicates, cursor, URL-as-state, facets #611)
• [Phase 9] Enforce the permission/projection chokepoint + cross-surface leak negative tests #622 — Permission/projection enforcement + the cross-surface leak negative-test bundle. (blocked on [Phase 9] Build the record shell: D4 header contract, tab registry, @drawer peek routes #613–[Phase 9] Build the CRM write path + audit: transactional command core, Audit tab + socket #620, [Phase 9] Build the Relationships tab + relationship-management slice (add/end/re-role) #625)
• [Phase 9] Fresh-build legacy deletion: donor grid, drawer, ?donor= machinery + CI symbol-grep #623 — Fresh-build legacy deletion: old donor grid, drawer, ?donor= machinery, monolithic detail service + the CI symbol-grep. (blocked on [Phase 9] Extend the party spine: lifecycle_status, tags, merge tombstone; regenerate seeds #606–[Phase 9] Enforce the permission/projection chokepoint + cross-surface leak negative tests #622, [Phase 9] Build the Relationships tab + relationship-management slice (add/end/re-role) #625, [Phase 9] Surface duplicates: header banner + /crm/duplicates queue into the Phase 4 workbench #626)
• [Phase 9] Phase 9 evidence file: safety-tier proof + Built/Live/Confirmed close-out #624 — Phase 9 evidence file (Built/Live/Confirmed) + safety-tier proof + parity-matrix flip. (blocked on [Phase 9] Assemble the permanent negative/safety tier + structural CI gates + e2e a11y #627)
• [Phase 9] Build the Relationships tab + relationship-management slice (add/end/re-role) #625 — Relationships tab + relationship-management slice (add / end / re-role; provenance display). (blocked on [Phase 9] Build the stored relationship graph: crm_relationships + seeded type catalog #607, [Phase 9] Build derived-edge views + the provenance UNION graph surface (supports_policy_v1) #608, [Phase 9] Build the record shell: D4 header contract, tab registry, @drawer peek routes #613, [Phase 9] Build the CRM write path + audit: transactional command core, Audit tab + socket #620)
• [Phase 9] Surface duplicates: header banner + /crm/duplicates queue into the Phase 4 workbench #626 — Duplicate visibility: header banner wiring + /crm/duplicates queue routing into the Phase 4 merge workbench ([Phase 4] Merge UI (dedupe queue + CRM-search multi-select → golden-record compare sheet) #514). (blocked on [Phase 9] Build the list-engine core + saved views: predicates, cursor, URL-as-state, facets #611, [Phase 9] Build /crm kind routes + navigation: layout chrome, pinned system views, queues #612, [Phase 9] Build the record shell: D4 header contract, tab registry, @drawer peek routes #613; hard prereq: [Phase 4] 🗺️ Epic — Identity & Account-Claiming Foundation #503)
• [Phase 9] Assemble the permanent negative/safety tier + structural CI gates + e2e a11y #627 — Permanent negative/safety tier assembly + structural CI gates + e2e a11y registration of every /crm* route. (blocked on [Phase 9] Extend the party spine: lifecycle_status, tags, merge tombstone; regenerate seeds #606–[Phase 9] Fresh-build legacy deletion: donor grid, drawer, ?donor= machinery + CI symbol-grep #623, [Phase 9] Build the Relationships tab + relationship-management slice (add/end/re-role) #625, [Phase 9] Surface duplicates: header banner + /crm/duplicates queue into the Phase 4 workbench #626)

Per the PRD's dependency notes, #606 carries status:blocked-on-Phase-4 and status:blocked-on-Phase-7-T4; #610 and #626 carry status:blocked-on-Phase-4. All other children are gated inside the phase via the blockers above.

Prerequisites & posture

• HARD — Phase 4 (epic [Phase 4] 🗺️ Epic — Identity & Account-Claiming Foundation #503): composite tenant keys, ENABLE+FORCE RLS, withTenant, the cross-tenant negative CI tier, and the A9 merge re-point contract (which this phase amends to add parties, crm_relationships, and the party-keyed engagement tables — PRD §C1). Duplicate/merge UX stays Phase-4-owned ([Phase 4] Merge UI (dedupe queue + CRM-search multi-select → golden-record compare sheet) #514); Phase 9 surfaces and links.
• HARD — Phase 7 T4, the party spine ([Phase 7] Party spine: parties supertype + persons anchor + households + household_members + org subtype + org_contacts + donors.party_id #570), as amended 2026-07-06 (PRD §C2): the committed flat party_type set becomes party_kind ∈ {person, household, org} (+ reserved 'group') with org_type on the org subtype; thin parties supertype with shared-PK subtyping; donors.party_id NOT NULL composite FK from the first migration; donors.party_type never created; frozen receipt snapshots copy the resolved taxonomy at issuance. Phase 9's [Phase 9] Extend the party spine: lifecycle_status, tags, merge tombstone; regenerate seeds #606 extends and verifies that spine — it never rebuilds it.
• SOFT — Phase 8 (per ADR-0001 §4): CRM writes are plain Asym writes with no provider gate (crm_write_gates withdrawn as a Twenty enabler). The only coupling is the Audit-tab ops-indicator socket, whose content the re-groomed Phase 8 ([Phase 8] Re-groom grill session — re-scope the CRM Operating Foundation on Asym-internal subjects (ADR-0001) #603, pending) owns. Phase 9 must not invent a gate.
• SOFT — Phase 6 (socket-only): the Communications tab socket and the "Request payment method update" / Write-a-Message action slots light up with Phase 6; nothing here blocks on it.
• Fresh-build posture (D6): no user-continuity ceremony; legacy replaced outright; old code is raw material reused on merit, not a constraint; but fresh-build never skips tenant isolation, migration-chain hygiene, merge auditability, frozen snapshots, consent/suppression gates, RLS discipline, the D3 enforcement tiers, the A11 PCI guardrails, or the irreversible graph-topology axes. "No users" softens nothing about getting topology 100% right the first time.

Done when

Verbatim from the PRD: "Staff can open a person, church, organization, or household and see a complete operational record without jumping to donor-specific pages or spreadsheets" — and no legacy donor grid, drawer, or detail routes remain.

Acceptance criteria

• All twenty-three children ([Phase 9] Docs foundation: party-topology ADR, OpenSpec delta, glossary + matrix discipline #605–[Phase 9] Assemble the permanent negative/safety tier + structural CI gates + e2e a11y #627) are closed.
• The done-when holds end-to-end in a seeded demo environment: every kind opens to the full A10 record shell (header + eight live tabs) from both the list drawer and the canonical detail page.
• No legacy donor grid, drawer, ?donor= state machine, or monolithic detail-service routes/symbols remain (D6 structural CI gate).
• The permanent negative/safety tier passes: cross-tenant isolation; derived-roles-never-authorize (import gate + runtime test); frozen roles-view shape; derived kinds rejected from the stored catalog; no member_care% relation in the timeline + member_care_private_notes RLS-revoked; restricted notes invisible via Notes tab and timeline; the four cross-surface leak tests (household grants zero portal access; no party notes/activity in missionary projections; no broad CRM enumeration from the missionary workspace; no CRM internals in donor-portal projections); FINANCE visibility + anonymity on giving-derived edges; search never leaks unreadable fields and excludes member-care/finance-provenance data; CSV export honors field policies; , % ( ) round-trip; stable keyset pagination over duplicate timestamps; merge re-point dedupe/tombstone/replayability.
• Structural CI gates pass: authz-import gate, roles-view schema-shape test, no-new-inline-contact-columns migration lint, every /crm* route registered in the e2e a11y spec, D6 legacy-deletion gate.
• No provider gate, provider-idempotency log, or crm_write_gates dependency exists anywhere in the phase (negative check; ADR-0001 §4).
• Seeds demonstrably include synthetic duplicate pairs, ≥1 merged tombstone per kind, and staff-assignment edges (E4) — dedupe queue, duplicate banner, and owner chips are populated in a fresh environment.
• The F1 ADR is authored; the §C1/§C2 amendment one-liners land on the Phase 4/Phase 7 PRDs; the C6 congruence touches land (phase-map row-9 soft-Phase-8 qualification, parity-matrix Phase 9 row, OpenSpec delta); the glossary pass lands in CONTEXT.md.
• The evidence file (Phase 0 Built/Live/Confirmed discipline, under docs/ops/phase-evidence/) records migrations applied, the full test suite incl. the negative tier, route/API checks, the seeded-demo walkthrough, and the explicit list of what Phase 9 did not build (the sockets and reserved seams).

Depends on

• Hard prerequisites (must land first): Phase 4 isolation plumbing + A9 merge contract — epic [Phase 4] 🗺️ Epic — Identity & Account-Claiming Foundation #503; Phase 7 §D/T4 as amended (§C2) — the party spine, [Phase 7] Party spine: parties supertype + persons anchor + households + household_members + org subtype + org_contacts + donors.party_id #570 (amended 2026-07-06).
• Soft: Phase 8 re-groom ([Phase 8] Re-groom grill session — re-scope the CRM Operating Foundation on Asym-internal subjects (ADR-0001) #603) for the Audit-tab socket content; Phase 6 for the comms/secure-link sockets.
• Do not start until: [Phase 4] 🗺️ Epic — Identity & Account-Claiming Foundation #503 (Phase 4 isolation plumbing + A9 merge contract) and [Phase 7] Party spine: parties supertype + persons anchor + households + household_members + org subtype + org_contacts + donors.party_id #570 (Phase 7 T4 party spine, as amended) have shipped. [Phase 9] Docs foundation: party-topology ADR, OpenSpec delta, glossary + matrix discipline #605 (docs) may proceed immediately; schema/build children gate per their own dependency lines.

Related (do not build here)

• Duplicate/merge UX — Phase-4-owned ([Phase 4] Merge UI (dedupe queue + CRM-search multi-select → golden-record compare sheet) #514). Phase 9 surfaces candidates and links into the workbench; destructive merge stays deferred unless explicitly approved.
• Consent gate — shipped in PR fix(email): gate outbound sends on donor consent and suppression list #502; inherited behind every send-adjacent action (§C4), never rebuilt.
• Twenty retirement cleanup — chore(crm): ADR-0001 cleanup — remove dormant Twenty CRM code, revoke keys, re-comment tables, archive integrate-twenty-crm-core #602 (package archive; retirement banners under docs/guides/features/twenty-crm-integration/** stay intact, verified by [Phase 9] Docs foundation: party-topology ADR, OpenSpec delta, glossary + matrix discipline #605).
• Phase 8 re-groom — [Phase 8] Re-groom grill session — re-scope the CRM Operating Foundation on Asym-internal subjects (ADR-0001) #603 owns the Audit-tab ops-indicator socket content; Phase 9 only reserves the socket.
• Prior machinery reused on merit — CRM Inline Operation Parity #270 inline gift-operation shell (retained in the Giving tab); CRM Gift-History View Settings #272–CRM Hub Shared Filter Definitions #274 named-views/operation-shell priors (storage model kept, payload schema generalized).
• Owned-elsewhere ladder (PRD Out of Scope): custom field builder → P11; admin permission config → P3/12; full giving ledger → P13/14; offline batch entry → P15; soft credit/DAF → P7/14; pledge management → P16; receipt/PDF templates → P18; year-end statements → P19; accounting exports → later Area-11; public page workflow → P5+; Site Planner → own phase; donor dashboard depth → P25; missionary dashboard depth → P28+; system message editor → P17; file manager → P29; Mailchimp sync → P32; import tool → P30; report builder → P33; workflow engine → P34; group kinds / groups + group_memberships → P37 (A8 guardrail).

🤖 Generated with Claude Code