@synap-core/workspace-templates 0.12.0 → 0.24.0

package/src/crm-messages-cadence.template.test.ts

@@ -0,0 +1,246 @@
+/**
+ * CRM messages and follow-up cadence (founder decisions of 2026-10-27, contract
+ * lanes/_briefs/crm-messages-cadence-2026-10-27.md, pod session ba6f39c8),
+ * pinned against the REAL YAML corpus. The CRM app shows the same words:
+ *
+ *   - CADENCE: 3 days after the first message, 7 days after each follow-up, at
+ *     most two follow-ups, never a third; ONE paragraph, word for word the same
+ *     in every process that sets the next follow-up after a send;
+ *   - DRAFT RULES (one send door, founder decisions d1/d5/d6 of 2026-11-02,
+ *     session d00cd2ac): a draft is a proposed message in the person's
+ *     channel, filed through the pod's `messaging.send` with `to` = their
+ *     entity id; never a tool's own send verb, never an outreach touch, never
+ *     synap_capture; ONE paragraph, word for word, in every drafter;
+ *   - the CADENCE counts the outbound messages in the lead's channels, and a
+ *     reply (an inbound message after our last outbound one) is read by
+ *     "Follow up on leads in outreach";
+ *   - "Read the reply to an outreach message" (the touches marked sent before
+ *     the channels) reads silence by the same dates and proposes nurturing
+ *     after the second follow-up;
+ *   - WHOSE MESSAGE (founder D3.1, wave 2 lane E2): a touch still belongs to
+ *     the lead it `relates_to` (REQUIRED link) until the touches are moved
+ *     into their channels; a proposed message belongs to the channel of the
+ *     person written to, so a drafter's output writes no edge.
+ *
+ * Does NOT cover what an agent does at run time (the goals are prose).
+ */
+
+import { describe, expect, it } from "vitest";
+import { readYamlTemplates } from "./generate.mjs";
+import type { WorkspaceYaml } from "./types.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const unipile = JSON.parse(
+  readFileSync(join(import.meta.dirname, "..", "capabilities", "unipile-linkedin.capability.json"), "utf8"),
+) as { spec: { skills: Array<{ name: string }> } };
+const corpus = readYamlTemplates().map((t) => t.data as WorkspaceYaml);
+const crm = corpus.find((x) => x.meta.slug === "crm")!;
+const playbookOf = (name: string) => {
+  const pb = crm.playbooks?.find((p) => p.name === name);
+  if (!pb) throw new Error(`playbook "${name}" not in crm`);
+  return pb;
+};
+const flat = (s: string | undefined) => (s ?? "").replace(/\s+/g, " ");
+const goalOf = (name: string) => flat(playbookOf(name).goalTemplate);
+const stageOf = (name: string, key: string) => {
+  const st = playbookOf(name).stages?.find((s) => s.key === key);
+  if (!st) throw new Error(`stage "${key}" not in "${name}"`);
+  return st;
+};
+
+const CADENCE =
+  'CADENCE: when a message is sent (a person approved its proposed message, so it is an outbound message in the channel), set its lead\'s lastContactedAt to the sent day, count the messages sent to the lead (the outbound messages in its channels, read with synap_get_channel mode person: for a company lead, the channels of the person written to there), and set the lead\'s next action: after the first message, nextAction "Follow up with <name> if no reply" and nextActionAt the sent day + 3 days; after the first follow-up, nextAction "Follow up with <name> a last time if no reply" and nextActionAt the sent day + 7 days; after the second follow-up, nextAction "No reply after two follow-ups: nurture or drop <name>" and nextActionAt the sent day + 7 days, and when that date passes with no reply, "Follow up on leads in outreach" proposes nurturing. Never a third follow-up. Propose moving a lead at new or researching to outreach through the status door, with its expected status. A reply stops the cadence: a reply is an inbound message after our last outbound one in the channel, and "Follow up on leads in outreach" reads it and proposes the next step.';
+
+/**
+ * The LinkedIn order (CRM wave 2, S4b, build map 6f6c197f; changed by the CRM
+ * Messages contract b4f8c2cd, decision b603d75e, build map ca310f27): a
+ * LinkedIn message is drafted WHATEVER the person's reach. The pod holds a
+ * first message to someone not connected when it is filed (backend#818,
+ * `data.held`) instead of refusing it (backend#786), so a drafter that held a
+ * draft back left the person with nothing to see. Find the profile and ask to
+ * connect still go alongside the draft. Part of the DRAFT RULES paragraph, so
+ * it is word for word the same in every drafter.
+ */
+const LINKEDIN_ORDER =
+  'A LinkedIn message is drafted whatever their reach: the pod holds a draft to someone who is not a connection yet, shows it with the next step and lets it go out once they connect, so never hold a draft back for want of a connection. Draft it, then, in this order: (1) a person with no linkedinUrl: find their profile with linkedin_find_profile (their full name and company); on a match, propose its linkedinUrl and linkedinProviderId on the person for a person to approve; on none or several, ask the person to choose among its candidates (the process "Find their LinkedIn" does this for one lead). (2) Read their linkedinConnection, which only the pod writes (never set it or linkedinInvitedAt): connected, nothing more; none or not set, ask to connect with linkedin_send_invite (it refuses someone already connected or already invited: then nothing more); pending, the draft waits for them; ignored, draft by email instead when they have an email address. While the draft waits for them to connect, set the lead\'s nextAction to "Wait for <name> to accept the LinkedIn request" and its nextActionAt 7 days later. An email message needs none of this.';
+
+const DRAFT_RULES =
+  "DRAFT RULES: each draft is one proposed message in the channel of the person it is written to, filed through the pod's send door: run messaging.send with to = that person's entity id (for a company lead, its decider: when that person is not in the pod, create them through the entity door with only their own fields, such as name, role and LinkedIn URL, never the company's website, domain or email), text = the message, and provider linkedin or email. Read their channel first (synap_get_channel, mode person) for what was already said. The pod files it for a person to review in that channel; it goes out only once they approve it. Never call a tool's own send verb (Unipile, Gmail), never create an outreach touch, a note or a task holding the message, and never use synap_capture for it. Never send. " +
+  LINKEDIN_ORDER;
+
+/** What a drafter yields: a `messaging.external.send` proposal (target type `messaging`). */
+const PROPOSED_MESSAGE = "messaging";
+const outputsOf = (p: NonNullable<WorkspaceYaml["playbooks"]>[number]) => [
+  ...(p.expectedOutputs ?? []),
+  ...(p.stages ?? []).flatMap((st) => st.expectedOutputs ?? []),
+];
+
+const SENDERS = ["Draft a first message", "Follow up on leads in outreach", "Personalized Outreach"];
+const DRAFTERS = ["Draft a first message", "Follow up on leads in outreach", "Personalized Outreach"];
+
+describe("CRM messages and cadence — catalog contract", () => {
+  it("one CADENCE paragraph, word for word, in every process that sets the follow-up after a send", () => {
+    for (const name of SENDERS) expect(goalOf(name), name).toContain(CADENCE);
+    // Only these: a fourth copy would be a second wording to keep in step.
+    const holders = (crm.playbooks ?? []).filter((p) => flat(p.goalTemplate).includes("CADENCE:")).map((p) => p.name);
+    expect(holders.sort()).toEqual([...SENDERS].sort());
+  });
+
+  it("no CRM process keeps the old weekly cadence or the 14-day silence default", () => {
+    const texts = (crm.playbooks ?? []).flatMap((p) => [
+      [p.name, flat(p.goalTemplate)],
+      ...(p.stages ?? []).flatMap((s) => [[`${p.name} › ${s.key}`, flat(s.goal)], ...(s.criteria ?? []).map((c) => [`${p.name} › ${c.key}`, flat(c.statement)])]),
+    ]);
+    const stale = texts.filter(([, t]) => /a week later|a week forward|14 days when it has none|polite last message/i.test(t!));
+    expect(stale.map(([w]) => w)).toEqual([]);
+  });
+
+  it("one DRAFT RULES paragraph in every drafter: messaging.send to the person, never a tool's send verb, an outreach touch or synap_capture", () => {
+    for (const name of DRAFTERS) expect(goalOf(name), name).toContain(DRAFT_RULES);
+    // Every process that drafts a proposed message is a drafter, and holds it.
+    const drafting = (crm.playbooks ?? []).filter((p) => outputsOf(p).some((o) => o.kind === PROPOSED_MESSAGE)).map((p) => p.name);
+    expect(drafting.sort()).toEqual([...DRAFTERS].sort());
+    const holders = (crm.playbooks ?? []).filter((p) => flat(p.goalTemplate).includes("DRAFT RULES:")).map((p) => p.name);
+    expect(holders.sort()).toEqual([...DRAFTERS].sort());
+    for (const part of [
+      "filed through the pod's send door: run messaging.send with to = that person's entity id",
+      "it goes out only once they approve it",
+      "Never call a tool's own send verb",
+      "never create an outreach touch",
+      "never use synap_capture",
+      "never the company's website, domain or email",
+    ])
+      expect(DRAFT_RULES).toContain(part);
+  });
+
+  it("'Draft a first message': send it to <name> today, then follow up 3 days after the send", () => {
+    const name = "Draft a first message";
+    expect(goalOf(name)).toContain('"Send the first message to <name> on LinkedIn"');
+    expect(flat(stageOf(name, "draft").goal)).toMatch(/as a proposed message in their channel through messaging\.send \(to = their entity id, never a tool's own send verb, never an outreach touch or synap_capture\)/);
+    const criteria = (stageOf(name, "draft").criteria ?? []).map((c) => [c.key, flat(c.statement)] as const);
+    expect(criteria.length).toBeLessThanOrEqual(5);
+    expect(Object.fromEntries(criteria)["first-message-one-draft"]).toMatch(/filed through messaging\.send to the person written to .* waits for review in that person's channel/);
+    expect(Object.fromEntries(criteria)["first-message-no-capture"]).toMatch(/send verb.*outreach touch.*synap_capture.*never the company's website, domain or email/);
+    expect(Object.fromEntries(criteria)["first-message-next-action"]).toContain('"Send the first message to <name>"');
+    expect(flat(stageOf(name, "send").goal)).toContain('nextAction "Follow up with <name> if no reply" and nextActionAt the sent day + 3 days');
+  });
+
+  it("'Follow up on leads in outreach': at most two follow-ups, 7 days after each, never a third", () => {
+    const name = "Follow up on leads in outreach";
+    expect(goalOf(name)).toContain("Draft at most two follow-ups per lead: a lead already sent two follow-ups gets no draft, never a third follow-up");
+    expect(flat(stageOf(name, "draft").goal)).toMatch(/or was already sent two follow-ups, gets none/);
+    const criteria = Object.fromEntries((stageOf(name, "draft").criteria ?? []).map((c) => [c.key, flat(c.statement)]));
+    expect(Object.keys(criteria).length).toBeLessThanOrEqual(5);
+    expect(criteria["followup-no-draft-after-reply"]).toMatch(/nor a third follow-up/);
+    expect(criteria["followup-draft-rules"]).toMatch(/proposed message filed through messaging\.send to the person written to .*no tool's own send verb .*outreach touch.*synap_capture/);
+    const send = flat(stageOf(name, "send").goal);
+    expect(send).toContain('after the first follow-up, nextAction "Follow up with <name> a last time if no reply" and nextActionAt the sent day + 7 days');
+    expect(send).toContain('after the second follow-up, nextAction "No reply after two follow-ups: nurture or drop <name>" and nextActionAt the sent day + 7 days');
+  });
+
+  it("CADENCE counts a lead's messages in its channels, never in outreach touches", () => {
+    expect(CADENCE).toContain("count the messages sent to the lead (the outbound messages in its channels");
+    expect(CADENCE).toContain("a reply is an inbound message after our last outbound one in the channel");
+    // The old rules (touches with a sent date; sent to the lead or its decider; a
+    // person marking a message sent) are gone from every CRM text.
+    const texts = (crm.playbooks ?? []).flatMap((p) => [flat(p.goalTemplate), ...(p.stages ?? []).map((s) => flat(s.goal))]);
+    expect(texts.length).toBeGreaterThan(20);
+    expect(texts.filter((t) => /sent to it or its decider|outreach touches with a sent date|person marks a message sent/.test(t))).toEqual([]);
+  });
+
+  it("the touch kind declares relates_to a lead (person or company) as its REQUIRED link, and only that", () => {
+    const links = crm.entityLinks ?? [];
+    const touchLinks = links.filter((l) => l.sourceProfileSlug === "outreach-touch");
+    // Non-vacuity: the touch's other links (sent_to, part_of) are seen too.
+    expect(touchLinks.map((l) => l.type).sort()).toEqual(["part_of", "relates_to", "relates_to", "sent_to"]);
+    const required = links.filter((l) => l.required === true).map((l) => `${l.sourceProfileSlug} -${l.type}-> ${l.targetProfileSlug}`);
+    expect(required.sort()).toEqual(["outreach-touch -relates_to-> company", "outreach-touch -relates_to-> person"]);
+    // The lead role is worn by a person or a company: the rule's targets are both.
+    for (const l of touchLinks.filter((x) => x.type === "relates_to")) expect(l.required).toBe(true);
+  });
+
+  it("every drafter yields proposed messages, which write no edge, and none yields an outreach touch", () => {
+    for (const name of DRAFTERS) {
+      const outputs = outputsOf(playbookOf(name));
+      expect(outputs.length, name).toBeGreaterThan(0);
+      // The channel is bound to the person already: a proposed message relates to nothing else.
+      for (const o of outputs) expect([o.kind, o.relationToSubject], `${name} › ${o.label}`).toEqual([PROPOSED_MESSAGE, "none"]);
+    }
+    // Decision d5: no CRM process drafts an outreach touch any more.
+    const touchMakers = (crm.playbooks ?? []).filter((p) => outputsOf(p).some((o) => o.kind === "outreach-touch")).map((p) => p.name);
+    expect(touchMakers).toEqual([]);
+  });
+
+  it("'Read the reply to an outreach message': silence is read by the cadence's dates, and nurturing follows the second follow-up", () => {
+    const name = "Read the reply to an outreach message";
+    const goal = goalOf(name);
+    expect(goal).toContain("the sent day + 3 days after the first message, the sent day + 7 days after each follow-up");
+    expect(goal).toMatch(/When this message is the second follow-up .* mark it no response and propose moving the lead to nurturing/);
+    expect(goal).not.toMatch(/14 days/);
+    expect(flat(stageOf(name, "no-response").goal)).toMatch(/after the second follow-up propose moving the lead to nurturing/);
+  });
+  it("the LinkedIn order: draft whatever their reach (the pod holds it), find the profile, ask to connect; the reach fields stay the pod's", () => {
+    for (const part of [
+      "A LinkedIn message is drafted whatever their reach",
+      "never hold a draft back for want of a connection",
+      "find their profile with linkedin_find_profile",
+      "propose its linkedinUrl and linkedinProviderId on the person for a person to approve",
+      "ask the person to choose among its candidates",
+      "never set it or linkedinInvitedAt",
+      "ask to connect with linkedin_send_invite",
+      "pending, the draft waits for them",
+      "ignored, draft by email instead",
+      "An email message needs none of this.",
+    ])
+      expect(LINKEDIN_ORDER).toContain(part);
+    for (const name of DRAFTERS) {
+      expect(goalOf(name), name).toContain(LINKEDIN_ORDER);
+      // Decision b603d75e (B): a draft is never held back for want of a connection.
+      // (A reply still gets no draft: "With a reply, draft nothing" stays, it is not about reach.)
+      for (const gone of ["goes only to a connection", "linkedin_send_invite and draft nothing", "wait and draft nothing", "candidates, or stop"])
+        expect(goalOf(name), `${name}: ${gone}`).not.toContain(gone);
+    }
+    // Every catalog verb the order names is a verb of the Unipile capability:
+    // a renamed or removed verb would leave the drafters calling nothing.
+    const named = [...LINKEDIN_ORDER.matchAll(/\b(linkedin_[a-z_]+)\b/g)].map((m) => m[1]);
+    expect(named.sort()).toEqual(["linkedin_find_profile", "linkedin_send_invite"]);
+    const verbs = unipile.spec.skills.map((s) => s.name);
+    for (const v of named) expect(verbs, v).toContain(v);
+    // The system person kind owns the reach fields (backend#786, machine-written):
+    // the CRM never declares them, so no CRM editor offers them.
+    const person = crm.profiles?.find((p) => p.slug === "person");
+    expect(person, "crm declares the person overlay").toBeTruthy();
+    const slugs = (person?.properties ?? []).map((p) => p.slug);
+    expect(slugs).toContain("linkedinUrl");
+    expect(slugs).not.toContain("linkedinConnection");
+    expect(slugs).not.toContain("linkedinInvitedAt");
+  });
+
+  it("'Find their LinkedIn': one lead, linkedin_find_profile, a proposal or up to 3 candidates, nothing sent", () => {
+    const name = "Find their LinkedIn";
+    const pb = playbookOf(name);
+    expect(pb.subjectProfile?.profileSlug).toBe("lead");
+    // The CRM app starts it for one lead, as "Draft a first message": params.lead.
+    expect(pb.params?.find((p) => p.name === "lead")).toMatchObject({ type: "entity", required: true });
+    expect(pb.params?.find((p) => p.name === "lead")).toEqual(playbookOf("Draft a first message").params?.find((p) => p.name === "lead"));
+    expect(pb.requiredIntents).toEqual(["enrich_entity"]);
+    const goal = goalOf(name);
+    expect(goal).toContain("run linkedin_find_profile with their full name, their company");
+    expect(goal).toContain("propose its linkedinUrl and linkedinProviderId on the person");
+    expect(goal).toContain("at most 3");
+    expect(goal).toContain("never set linkedinConnection or linkedinInvitedAt");
+    // A reader: it never asks to connect nor drafts (those are the other steps).
+    const named = [...goal.matchAll(/\b((?:linkedin|unipile)_[a-z_]+)\b/g)].map((m) => m[1]);
+    expect(named.sort()).toEqual(["linkedin_find_profile", "unipile_list_accounts"]);
+    const verbs = unipile.spec.skills.map((s) => s.name);
+    for (const v of named) expect(verbs, v).toContain(v);
+    // The verb it runs answers the intent it requires.
+    const find = (unipile.spec.skills as Array<{ name: string; intent?: string }>).find((s) => s.name === "linkedin_find_profile");
+    expect(find?.intent).toBe("enrich_entity");
+    // The person decides what lands on the person.
+    expect(stageOf(name, "confirm").gate).toEqual({ kind: "human" });
+    // The drafters point at it by its exact name.
+    expect(LINKEDIN_ORDER).toContain(`the process "${name}"`);
+  });
+});

package/src/crm-one-send-door.template.test.ts

@@ -0,0 +1,65 @@
+/**
+ * One send door (founder decisions d1, d5, d6 of 2026-11-02, pod session
+ * d00cd2ac), pinned against the REAL YAML corpus:
+ *
+ *   - every CRM process that writes to a person files a proposed message
+ *     through the pod's `messaging.send` (a `messaging.external.send` proposal
+ *     on the person's channel), and none names a tool's own send verb;
+ *   - the CRM's "LinkedIn conversation ingest" automation is gone: the pod's
+ *     messaging webhook and its history import record LinkedIn messages in the
+ *     channels (backend channels release). It also filtered accounts on
+ *     `item.type == 'LINKEDIN'`, which Unipile v2 rows never carry.
+ *
+ * The paragraphs themselves (DRAFT RULES, CADENCE) are pinned word for word in
+ * crm-messages-cadence.template.test.ts; the Unipile verbs' intents in
+ * send-message-maps.test.ts.
+ *
+ * Does NOT cover what an agent does at run time (the goals are prose), nor the
+ * pod serving `messaging.send` (backend).
+ */
+
+import { describe, expect, it } from "vitest";
+import { readYamlTemplates } from "./generate.mjs";
+import type { WorkspaceYaml } from "./types.js";
+
+const corpus = readYamlTemplates().map((t) => t.data as WorkspaceYaml);
+const crm = corpus.find((x) => x.meta.slug === "crm")!;
+const flat = (s: string | undefined) => (s ?? "").replace(/\s+/g, " ");
+/** Every text an agent reads in a playbook: goal, description, stage goals, criteria. */
+const textsOf = (p: NonNullable<WorkspaceYaml["playbooks"]>[number]) => [
+  flat(p.goalTemplate),
+  flat(p.description),
+  ...(p.stages ?? []).flatMap((s) => [flat(s.goal), ...(s.criteria ?? []).map((c) => flat(c.statement))]),
+];
+/** The catalog's own send verbs (Unipile, Gmail, Slack): agent tool calls, never a process's door. */
+const TOOL_SEND_VERBS = /\b(unipile_send_message|unipile_start_chat|linkedin_send_first_message|gmail_send|slack_send_message)\b/;
+const automationKeys = (t: WorkspaceYaml) =>
+  ((t as { automations?: Array<{ key?: string }> }).automations ?? []).map((a) => a.key);
+
+describe("CRM — one send door", () => {
+  it("non-vacuity: the corpus and CRM's processes are read", () => {
+    expect(corpus.length).toBeGreaterThanOrEqual(25);
+    expect((crm.playbooks ?? []).length).toBeGreaterThanOrEqual(8);
+  });
+
+  it("every CRM process that drafts a message files it through messaging.send", () => {
+    const drafters = (crm.playbooks ?? []).filter((p) => flat(p.goalTemplate).includes("DRAFT RULES:"));
+    expect(drafters.map((p) => p.name).sort()).toEqual(["Draft a first message", "Follow up on leads in outreach", "Personalized Outreach"]);
+    for (const p of drafters) expect(flat(p.goalTemplate), p.name).toMatch(/run messaging\.send with to = that person's entity id/);
+  });
+
+  it("no process in any template names a tool's own send verb", () => {
+    const naming = corpus.flatMap((t) =>
+      (t.playbooks ?? []).filter((p) => textsOf(p).some((x) => TOOL_SEND_VERBS.test(x))).map((p) => `${t.meta.slug} › ${p.name}`)
+    );
+    expect(naming).toEqual([]);
+  });
+
+  it("the LinkedIn ingest automation is gone from every template", () => {
+    expect(automationKeys(crm)).not.toContain("linkedin-conversation-ingest");
+    const carrying = corpus.filter((t) => automationKeys(t).includes("linkedin-conversation-ingest")).map((t) => t.meta.slug);
+    expect(carrying).toEqual([]);
+    // Nothing else in the CRM still drives the old ingest verb.
+    expect(JSON.stringify(crm)).not.toMatch(/channel\.ingest|unipile_list_conversations|unipile_list_messages/);
+  });
+});