fullstackgtm 0.14.1 → 0.16.0

package/src/marketReport.ts

@@ -0,0 +1,272 @@
+import type {
+  ClaimFront,
+  FrontState,
+  MarketConfig,
+  MarketObservation,
+  ObservationSet,
+} from "./market.ts";
+import { computeFrontStates } from "./market.ts";
+
+/**
+ * Render a market map as a client-ready deliverable: markdown for terminals
+ * and PRs, and a self-contained printable HTML "field report" — front
+ * summary, claim × vendor intensity matrix, and a verbatim-evidence
+ * appendix. Deterministic: same observation set, same bytes. No webfonts,
+ * no CDNs — the artifact must stand alone wherever it's sent.
+ */
+
+const FRONT_ORDER: Record<FrontState, number> = {
+  open: 0,
+  contested: 1,
+  owned: 2,
+  saturated: 3,
+  vacant: 4,
+};
+
+const GLYPH: Record<string, string> = {
+  loud: "■",
+  quiet: "□",
+  absent: "·",
+  unobservable: "▨",
+};
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+type MapModel = {
+  config: MarketConfig;
+  set: ObservationSet;
+  fronts: ClaimFront[];
+  /** claims sorted open-first, then by id — the report's reading order. */
+  orderedClaimIds: string[];
+  cell: (vendorId: string, claimId: string) => MarketObservation | undefined;
+};
+
+function buildModel(config: MarketConfig, set: ObservationSet): MapModel {
+  const fronts = computeFrontStates(config, set);
+  const stateByClaim = new Map(fronts.map((front) => [front.claimId, front.state]));
+  const orderedClaimIds = config.claims
+    .map((claim) => claim.id)
+    .sort((a, b) => {
+      const byFront = FRONT_ORDER[stateByClaim.get(a) ?? "vacant"] - FRONT_ORDER[stateByClaim.get(b) ?? "vacant"];
+      return byFront !== 0 ? byFront : a.localeCompare(b);
+    });
+  const byCell = new Map(set.observations.map((obs) => [`${obs.vendorId}|${obs.claimId}`, obs]));
+  return {
+    config,
+    set,
+    fronts,
+    orderedClaimIds,
+    cell: (vendorId, claimId) => byCell.get(`${vendorId}|${claimId}`),
+  };
+}
+
+export function marketMapToMarkdown(config: MarketConfig, set: ObservationSet): string {
+  const model = buildModel(config, set);
+  const stateByClaim = new Map(model.fronts.map((front) => [front.claimId, front.state]));
+  const counts: Record<FrontState, number> = { open: 0, contested: 0, owned: 0, saturated: 0, vacant: 0 };
+  for (const front of model.fronts) counts[front.state] += 1;
+
+  const lines: string[] = [];
+  lines.push(`# Market map — ${config.category} (${set.runLabel})`);
+  lines.push("");
+  lines.push(
+    `Observed ${set.runAt} · ${config.vendors.length} vendors · ${config.claims.length} claims · ` +
+      `${set.observations.length} readings · extractor ${set.extractor}`,
+  );
+  lines.push("");
+  lines.push(
+    `Fronts: ${counts.open + counts.vacant} open/vacant · ${counts.contested} contested · ` +
+      `${counts.owned} owned · ${counts.saturated} saturated`,
+  );
+  lines.push("");
+  lines.push(`Legend: ■ loud · □ quiet · · absent · ▨ unobservable`);
+  lines.push("");
+  const header = ["claim", ...config.vendors.map((v) => v.id), "front"];
+  lines.push(`| ${header.join(" | ")} |`);
+  lines.push(`| ${header.map(() => "---").join(" | ")} |`);
+  for (const claimId of model.orderedClaimIds) {
+    const cells = config.vendors.map((vendor) => GLYPH[model.cell(vendor.id, claimId)?.intensity ?? "unobservable"]);
+    lines.push(`| ${claimId} | ${cells.join(" | ")} | ${stateByClaim.get(claimId)?.toUpperCase()} |`);
+  }
+  lines.push("");
+  for (const front of model.fronts.filter((f) => f.state === "owned")) {
+    lines.push(`- OWNED: ${front.claimId} → ${front.loudVendorIds[0]}`);
+  }
+  for (const front of model.fronts.filter((f) => f.state === "open" || f.state === "vacant")) {
+    lines.push(`- ${front.state.toUpperCase()}: ${front.claimId} — no vendor is loud here`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function marketMapToHtml(config: MarketConfig, set: ObservationSet): string {
+  const model = buildModel(config, set);
+  const stateByClaim = new Map(model.fronts.map((front) => [front.claimId, front.state]));
+  const claimsById = new Map(config.claims.map((claim) => [claim.id, claim]));
+  const counts: Record<FrontState, number> = { open: 0, contested: 0, owned: 0, saturated: 0, vacant: 0 };
+  for (const front of model.fronts) counts[front.state] += 1;
+  const unobservable = set.observations.filter((obs) => obs.intensity === "unobservable").length;
+  const anchor = config.anchorVendor;
+  const e = escapeHtml;
+
+  const matrixRows = model.orderedClaimIds
+    .map((claimId) => {
+      const claim = claimsById.get(claimId);
+      if (!claim) return "";
+      const state = stateByClaim.get(claimId) ?? "vacant";
+      const cells = config.vendors
+        .map((vendor) => {
+          const intensity = model.cell(vendor.id, claimId)?.intensity ?? "unobservable";
+          const anchorClass = vendor.id === anchor ? " anchor-col" : "";
+          return `<td class="cell${anchorClass}"><span class="g g-${intensity}" title="${e(vendor.name)}: ${intensity}"></span></td>`;
+        })
+        .join("");
+      return (
+        `<tr class="front-${state}"><th scope="row"><span class="claim-cap">${e(claim.capability.split(":")[0])}</span>` +
+        `<span class="claim-meta">${e(claim.icp)} · ${e(claim.pricingStructure)}</span></th>${cells}` +
+        `<td class="front"><span class="chip chip-${state}">${state.toUpperCase()}</span></td></tr>`
+      );
+    })
+    .join("");
+
+  const openList = model.orderedClaimIds
+    .filter((claimId) => {
+      const state = stateByClaim.get(claimId);
+      return state === "open" || state === "vacant";
+    })
+    .map((claimId) => {
+      const claim = claimsById.get(claimId);
+      return `<li><b>${e(claim?.capability.split(":")[0] ?? claimId)}</b> <span class="why">— no vendor is loud here; ${e(claim?.icp ?? "")} cell</span></li>`;
+    })
+    .join("");
+
+  const appendix = model.orderedClaimIds
+    .flatMap((claimId) =>
+      config.vendors.flatMap((vendor) => {
+        const obs = model.cell(vendor.id, claimId);
+        if (!obs || obs.evidence.length === 0) return [];
+        return obs.evidence.map(
+          (evidence) =>
+            `<div class="ev"><span class="ev-head">${e(vendor.name)} · ${e(claimId)} · ${obs.intensity.toUpperCase()} (${obs.confidence})</span>` +
+            `<blockquote>“${e(evidence.text)}”</blockquote>` +
+            `<span class="ev-src">${e(String(evidence.metadata?.url ?? ""))} · capture ${e(String(evidence.metadata?.captureHash ?? "").slice(0, 12))}</span></div>`,
+        );
+      }),
+    )
+    .join("");
+
+  const vendorHeads = config.vendors
+    .map(
+      (vendor) =>
+        `<th class="vh${vendor.id === anchor ? " anchor-col" : ""}"><span>${e(vendor.name)}</span></th>`,
+    )
+    .join("");
+
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Market map — ${e(config.category)} — ${e(set.runLabel)}</title>
+<style>
+:root { --paper:#f4efe4; --ink:#211d16; --ink-soft:#5a5244; --line:#c9bfa9; --accent:#b4441b; --green:#2e5339; --quiet:#8a7d63; }
+* { box-sizing:border-box; margin:0; }
+body { font-family:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif; color:var(--ink); background:var(--paper);
+  max-width:1080px; margin:0 auto; padding:0 48px 96px;
+  background-image:radial-gradient(rgba(33,29,22,.028) 1px, transparent 1.2px); background-size:5px 5px; }
+.chip,.claim-meta,.ev-src,.lg,.stamp,.meta,th.vh span { font-family:"SF Mono",Menlo,Consolas,monospace; }
+header { padding:56px 0 28px; border-bottom:3px double var(--ink); position:relative; }
+.kicker { font-size:11px; letter-spacing:.32em; color:var(--accent); text-transform:uppercase; }
+h1 { font-size:44px; line-height:1.05; font-weight:600; margin:10px 0 6px; }
+h1 em { font-style:italic; color:var(--green); }
+.meta { font-size:11.5px; color:var(--ink-soft); display:flex; gap:24px; flex-wrap:wrap; margin-top:14px; }
+.stamp { position:absolute; right:0; top:58px; border:2px solid var(--accent); color:var(--accent); padding:7px 13px;
+  font-size:11px; letter-spacing:.22em; transform:rotate(3.5deg); text-transform:uppercase; }
+section { margin-top:56px; }
+h2 { font-size:13px; letter-spacing:.26em; text-transform:uppercase; color:var(--ink-soft);
+  border-bottom:1px solid var(--line); padding-bottom:9px; display:flex; gap:14px; align-items:baseline; }
+h2 .no { color:var(--accent); font-style:italic; font-size:15px; letter-spacing:0; }
+.fronts { display:grid; grid-template-columns:repeat(4,1fr); gap:1px; background:var(--line); border:1px solid var(--line); margin-top:22px; }
+.fcard { background:var(--paper); padding:18px 18px 14px; }
+.fcard b { display:block; font-size:42px; font-weight:600; line-height:1; }
+.fcard span { font-size:11px; letter-spacing:.18em; text-transform:uppercase; color:var(--ink-soft); }
+.fcard.open b { color:var(--accent); }
+.openlist { margin-top:18px; font-size:15.5px; line-height:1.55; }
+.openlist li { margin:4px 0 4px 20px; }
+.openlist .why { color:var(--ink-soft); font-size:13px; font-style:italic; }
+.legend { display:flex; gap:22px; flex-wrap:wrap; margin:18px 0 10px; font-size:10.5px; color:var(--ink-soft); }
+.lg { display:inline-flex; align-items:center; gap:7px; }
+table { border-collapse:collapse; width:100%; margin-top:6px; }
+thead th { border-bottom:2px solid var(--ink); padding:6px 2px 10px; }
+th.vh span { writing-mode:vertical-rl; transform:rotate(195deg); font-size:10.5px; letter-spacing:.12em;
+  text-transform:uppercase; color:var(--ink-soft); display:inline-block; }
+th.vh.anchor-col span { color:var(--green); font-weight:700; }
+tbody th { text-align:left; font-weight:400; padding:7px 14px 7px 0; border-bottom:1px solid var(--line); max-width:330px; }
+.claim-cap { display:block; font-size:14.5px; }
+.claim-meta { display:block; font-size:9.5px; color:var(--quiet); letter-spacing:.08em; margin-top:2px; }
+td.cell { text-align:center; border-bottom:1px solid var(--line); padding:4px 2px; }
+td.cell.anchor-col { background:rgba(46,83,57,.06); }
+td.front { border-bottom:1px solid var(--line); text-align:right; white-space:nowrap; }
+.g { display:inline-block; width:15px; height:15px; vertical-align:middle; }
+.g-loud { background:var(--ink); }
+.g-quiet { box-shadow:inset 0 0 0 2px var(--quiet); }
+.g-absent { background:radial-gradient(circle at center, var(--line) 0 2.5px, transparent 3px); }
+.g-unobservable { background:repeating-linear-gradient(45deg, var(--line) 0 2px, transparent 2px 5px); }
+tr.front-open th .claim-cap { color:var(--accent); font-weight:600; }
+.chip { font-size:9px; letter-spacing:.16em; padding:3px 8px; border:1px solid currentColor; }
+.chip-open { color:var(--accent); } .chip-contested { color:#7a5a12; }
+.chip-owned { color:var(--green); } .chip-saturated { color:var(--ink-soft); } .chip-vacant { color:var(--quiet); }
+.ev { border-bottom:1px solid var(--line); padding:12px 0; }
+.ev-head { font-size:10.5px; letter-spacing:.1em; color:var(--accent); }
+.ev blockquote { font-style:italic; margin:6px 0; font-size:13.5px; line-height:1.5; }
+.ev-src { font-size:10px; color:var(--ink-soft); word-break:break-all; }
+footer { margin-top:72px; border-top:3px double var(--ink); padding-top:14px; font-size:11px; color:var(--ink-soft);
+  display:flex; justify-content:space-between; gap:20px; flex-wrap:wrap; }
+@media print { body { max-width:none; padding:0 8mm; background:white; } section { break-inside:avoid-page; } tr { break-inside:avoid; } }
+</style></head><body>
+<header>
+  <div class="kicker">Full Stack GTM · Market Map</div>
+  <h1>The <em>${e(config.category.replace(/-/g, " "))}</em> front map</h1>
+  <div class="meta">
+    <span>RUN ${e(set.runLabel.toUpperCase())}</span><span>OBSERVED ${e(set.runAt)}</span>
+    <span>${config.vendors.length} VENDORS · ${config.claims.length} CLAIMS · ${set.observations.length} READINGS</span>
+    <span>${unobservable} UNOBSERVABLE · EXTRACTOR ${e(set.extractor)}</span>
+  </div>
+  <div class="stamp">Field Report</div>
+</header>
+<section>
+  <h2><span class="no">01</span> Front summary</h2>
+  <div class="fronts">
+    <div class="fcard open"><b>${counts.open + counts.vacant}</b><span>Open / vacant</span></div>
+    <div class="fcard"><b>${counts.contested}</b><span>Contested</span></div>
+    <div class="fcard"><b>${counts.owned}</b><span>Owned</span></div>
+    <div class="fcard"><b>${counts.saturated}</b><span>Saturated</span></div>
+  </div>
+  <ul class="openlist">${openList}</ul>
+</section>
+<section>
+  <h2><span class="no">02</span> Claim × vendor intensity matrix</h2>
+  <div class="legend">
+    <span class="lg"><i class="g g-loud"></i>LOUD — hero-level claim</span>
+    <span class="lg"><i class="g g-quiet"></i>QUIET — shipped, buried</span>
+    <span class="lg"><i class="g g-absent"></i>ABSENT</span>
+    <span class="lg"><i class="g g-unobservable"></i>UNOBSERVABLE — capture failed</span>
+  </div>
+  <table>
+    <thead><tr><th></th>${vendorHeads}<th></th></tr></thead>
+    <tbody>${matrixRows}</tbody>
+  </table>
+</section>
+<section>
+  <h2><span class="no">03</span> Evidence appendix</h2>
+  ${appendix}
+</section>
+<footer>
+  <span>Generated by fullstackgtm market · deterministic render of ${e(set.runLabel)}</span>
+  <span>Front rule v1: 0 loud=open · 1=owned · 2–3=contested · ≥4=saturated</span>
+</footer>
+</body></html>`;
+}

package/src/mcp.ts

@@ -48,6 +48,7 @@ import { builtinAuditRules } from "./rules.ts";
 import { sampleSnapshot } from "./sampleData.ts";
 import { normalizeTranscript, parseCall } from "./calls.ts";
 import { extractInsightsLlm, resolveLlmCredential } from "./llm.ts";
+import { resolveRecord } from "./resolve.ts";
 import { suggestValues } from "./suggest.ts";
 import type { CanonicalGtmSnapshot, GtmConnector, PatchPlan } from "./types.ts";
 
@@ -239,6 +240,31 @@ export async function startMcpServer() {
     },
   );
 
+  server.registerTool(
+    "fullstackgtm_resolve",
+    {
+      title: "Resolve Record (create gate)",
+      description:
+        "Before creating a CRM record, check whether it already exists. Returns a verdict " +
+        "(exists | ambiguous | safe_to_create) with matches and a reason, using the same " +
+        "identity keys as the audit/merge engines (account domain, contact email, open-deal " +
+        "key). Read-only. Never create on 'exists' or 'ambiguous'.",
+      inputSchema: {
+        objectType: z.enum(["account", "contact", "deal"]),
+        name: z.string().optional(),
+        domain: z.string().optional(),
+        email: z.string().optional(),
+        accountId: z.string().optional(),
+        provider: z.enum(["sample", "demo", "hubspot", "salesforce", "stripe"]).optional(),
+        inputPath: z.string().optional(),
+      },
+    },
+    async ({ objectType, name, domain, email, accountId, provider, inputPath }) => {
+      const snapshot = await readSnapshot(provider, inputPath);
+      return content(resolveRecord(snapshot, { objectType, name, domain, email, accountId }));
+    },
+  );
+
   server.registerTool(
     "fullstackgtm_rules",
     {

package/src/merge.ts

@@ -52,7 +52,7 @@ export type MergeReport = {
 };
 
 const CONFLICT_IGNORED_FIELDS = new Set([
-  "id", "provider", "crmId", "identities", "raw", "lastSyncAt", "lastActivityAt", "ownerId", "accountId",
+  "id", "provider", "crmId", "identities", "raw", "lastSyncAt", "lastActivityAt", "ownerId", "accountId", "provenance",
 ]);
 
 export function normalizeDomain(domain?: string): string | undefined {

package/src/resolve.ts

@@ -0,0 +1,177 @@
+import { normalizeDomain } from "./merge.ts";
+import type { CanonicalGtmSnapshot } from "./types.ts";
+
+/**
+ * The resolve gate — the Prevent layer of the CRM-health lifecycle.
+ *
+ * Before any writer (sync job, webhook handler, agent, this CLI's own
+ * `create:` path) creates a record, it should ask: does this record already
+ * exist? The gate answers deterministically from a snapshot using the same
+ * identity keys the audit and merge engines use:
+ *
+ *   account → normalized domain (exact), then normalized name
+ *   contact → normalized email (exact), then full name
+ *   deal    → open-deal key: (accountId | "unlinked") + normalized name
+ *
+ * Verdicts are gate-shaped: `exists` (link to it, don't create),
+ * `ambiguous` (a human must pick — do NOT blind-create), `safe_to_create`.
+ */
+
+export type ResolveCandidate = {
+  objectType: "account" | "contact" | "deal";
+  name?: string;
+  domain?: string;
+  email?: string;
+  /** For deals: scope the duplicate key to an account. */
+  accountId?: string;
+};
+
+export type ResolveMatch = {
+  id: string;
+  name: string;
+  matchedBy: "domain" | "email" | "name" | "deal_key";
+  detail: string;
+};
+
+export type ResolveResult = {
+  objectType: ResolveCandidate["objectType"];
+  verdict: "exists" | "ambiguous" | "safe_to_create";
+  matches: ResolveMatch[];
+  reason: string;
+};
+
+export function resolveRecord(
+  snapshot: CanonicalGtmSnapshot,
+  candidate: ResolveCandidate,
+): ResolveResult {
+  if (candidate.objectType === "account") return resolveAccount(snapshot, candidate);
+  if (candidate.objectType === "contact") return resolveContact(snapshot, candidate);
+  return resolveDeal(snapshot, candidate);
+}
+
+function resolveAccount(snapshot: CanonicalGtmSnapshot, c: ResolveCandidate): ResolveResult {
+  const base = { objectType: "account" as const };
+  const domain = normalizeDomain(c.domain);
+  if (domain) {
+    const matches = snapshot.accounts
+      .filter((a) => normalizeDomain(a.domain) === domain)
+      .map((a) => match(a.id, a.name, "domain", `account domain ${a.domain} normalizes to ${domain}`));
+    if (matches.length === 1) {
+      return { ...base, verdict: "exists", matches, reason: `An account with domain ${domain} already exists: "${matches[0].name}" (${matches[0].id}). Link to it instead of creating.` };
+    }
+    if (matches.length > 1) {
+      return { ...base, verdict: "ambiguous", matches, reason: `${matches.length} accounts already share domain ${domain} — that's a duplicate group; merge it before adding more. Do not create.` };
+    }
+  }
+  if (c.name) {
+    const key = normalizeName(c.name);
+    const matches = snapshot.accounts
+      .filter((a) => normalizeName(a.name) === key)
+      .map((a) => match(a.id, a.name, "name", `account name matches "${c.name}" (domain: ${a.domain ?? "none"})`));
+    if (matches.length > 0) {
+      // Name alone is suggestive, not identity — two real companies can share
+      // a name (the merge engine treats this the same way).
+      return {
+        ...base,
+        verdict: "ambiguous",
+        matches,
+        reason: `${matches.length} account(s) named "${c.name}" exist but ${domain ? `none share domain ${domain}` : "no domain was supplied to confirm identity"}. Confirm before creating — supply a domain to disambiguate.`,
+      };
+    }
+  }
+  if (!domain && !c.name) {
+    return { ...base, verdict: "ambiguous", matches: [], reason: "Supply --domain and/or --name to resolve an account." };
+  }
+  return { ...base, verdict: "safe_to_create", matches: [], reason: `No account matches ${domain ? `domain ${domain}` : `name "${c.name}"`}. Safe to create.` };
+}
+
+function resolveContact(snapshot: CanonicalGtmSnapshot, c: ResolveCandidate): ResolveResult {
+  const base = { objectType: "contact" as const };
+  const email = c.email?.trim().toLowerCase();
+  if (email) {
+    const matches = snapshot.contacts
+      .filter((row) => row.email?.trim().toLowerCase() === email)
+      .map((row) => match(row.id, contactName(row), "email", `contact email matches ${email}`));
+    if (matches.length === 1) {
+      return { ...base, verdict: "exists", matches, reason: `A contact with email ${email} already exists: "${matches[0].name}" (${matches[0].id}). Update it instead of creating.` };
+    }
+    if (matches.length > 1) {
+      return { ...base, verdict: "ambiguous", matches, reason: `${matches.length} contacts already share ${email} — a duplicate group; merge before adding more. Do not create.` };
+    }
+    return { ...base, verdict: "safe_to_create", matches: [], reason: `No contact matches ${email}. Safe to create.` };
+  }
+  if (c.name) {
+    const key = normalizeName(c.name);
+    const matches = snapshot.contacts
+      .filter((row) => normalizeName(contactName(row)) === key)
+      .map((row) => match(row.id, contactName(row), "name", `contact name matches "${c.name}" (email: ${row.email ?? "none"})`));
+    if (matches.length > 0) {
+      return { ...base, verdict: "ambiguous", matches, reason: `${matches.length} contact(s) named "${c.name}" exist; names are not identity. Supply --email to resolve definitively.` };
+    }
+    return { ...base, verdict: "safe_to_create", matches: [], reason: `No contact named "${c.name}". Safe to create — but prefer resolving by email.` };
+  }
+  return { ...base, verdict: "ambiguous", matches: [], reason: "Supply --email (preferred) or --name to resolve a contact." };
+}
+
+function resolveDeal(snapshot: CanonicalGtmSnapshot, c: ResolveCandidate): ResolveResult {
+  const base = { objectType: "deal" as const };
+  if (!c.name) {
+    return { ...base, verdict: "ambiguous", matches: [], reason: "Supply --name (and ideally --account-id) to resolve a deal." };
+  }
+  const nameKey = normalizeName(c.name);
+  const open = snapshot.deals.filter((d) => d.isClosed !== true && d.isWon !== true);
+  if (c.accountId) {
+    const key = `${c.accountId}:${nameKey}`;
+    const matches = open
+      .filter((d) => `${d.accountId ?? "unlinked"}:${normalizeName(d.name)}` === key)
+      .map((d) => match(d.id, d.name, "deal_key", `open deal with the same name on account ${c.accountId}`));
+    if (matches.length > 0) {
+      return {
+        ...base,
+        verdict: "exists",
+        matches,
+        reason: `${matches.length} open deal(s) already match "${c.name}" on account ${c.accountId} — creating another would double-count pipeline. Update the existing deal.`,
+      };
+    }
+    const closedSameName = snapshot.deals.filter(
+      (d) =>
+        (d.isClosed === true || d.isWon === true) &&
+        d.accountId === c.accountId &&
+        normalizeName(d.name) === nameKey,
+    );
+    return {
+      ...base,
+      verdict: "safe_to_create",
+      matches: [],
+      reason: closedSameName.length > 0
+        ? `No open deal matches on account ${c.accountId}; ${closedSameName.length} closed deal(s) on it share the name (a re-open/renewal may be intended). Safe to create.`
+        : `No open deal matches "${c.name}" on account ${c.accountId}. Safe to create.`,
+    };
+  }
+  // No account scope: name-only matches across ALL open deals are ambiguous,
+  // never safe — a gate that ignores name collisions protects nobody.
+  const sameName = open
+    .filter((d) => normalizeName(d.name) === nameKey)
+    .map((d) => match(d.id, d.name, "name", `open deal with the same name on ${d.accountId ? `account ${d.accountId}` : "no account"}`));
+  if (sameName.length > 0) {
+    return {
+      ...base,
+      verdict: "ambiguous",
+      matches: sameName,
+      reason: `${sameName.length} open deal(s) named "${c.name}" exist (no --account-id supplied to scope the check). Confirm before creating — supply --account-id to resolve definitively.`,
+    };
+  }
+  return { ...base, verdict: "safe_to_create", matches: [], reason: `No open deal named "${c.name}" anywhere. Safe to create.` };
+}
+
+function contactName(row: { firstName?: string; lastName?: string }) {
+  return [row.firstName, row.lastName].filter(Boolean).join(" ") || "(unnamed)";
+}
+
+function normalizeName(value: string) {
+  return value.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+function match(id: string, name: string, matchedBy: ResolveMatch["matchedBy"], detail: string): ResolveMatch {
+  return { id, name, matchedBy, detail };
+}

package/src/rules.ts

@@ -21,6 +21,27 @@ export function requiresHumanInput(value: unknown): boolean {
   return typeof value === "string" && value.startsWith(REQUIRES_HUMAN_PREFIX);
 }
 
+/**
+ * Attribution for duplicate groups: when the provider exposes record-source
+ * provenance (RecordProvenance), name the writer(s) that created the group —
+ * the fix for recurring dupes is upstream in the writer, not in the records.
+ */
+export function provenanceSummary(records: Array<{ provenance?: { source?: string; sourceLabel?: string; sourceId?: string } }>): string {
+  const counts = new Map<string, number>();
+  for (const record of records) {
+    const p = record.provenance;
+    if (!p) continue;
+    const label = p.sourceLabel ?? p.source ?? "unknown source";
+    const key = p.sourceId ? `${label} (${p.sourceId})` : label;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  if (counts.size === 0) return "";
+  const parts = [...counts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .map(([key, count]) => (count > 1 ? `${key} ×${count}` : key));
+  return ` Created by: ${parts.join(", ")}.`;
+}
+
 export function auditFindingId(ruleId: string, objectId: string) {
   return `finding_${stableHash(`${ruleId}:${objectId}`)}`;
 }
@@ -343,7 +364,7 @@ export const duplicateAccountDomainRule: GtmAuditRule = {
         ruleId: "duplicate-account-domain",
         title: "Accounts share the same domain",
         severity: "warning",
-        summary: `${accounts.length} accounts share ${domain}: ${accounts.map((account) => account.name).join(", ")}.`,
+        summary: `${accounts.length} accounts share ${domain}: ${accounts.map((account) => account.name).join(", ")}.${provenanceSummary(accounts)}`,
         recommendation: "Review the group and merge duplicates so activity and deals roll up once.",
       });
       operations.push({
@@ -383,7 +404,7 @@ export const duplicateContactEmailRule: GtmAuditRule = {
         ruleId: "duplicate-contact-email",
         title: "Contacts share the same email",
         severity: "warning",
-        summary: `${contacts.length} contacts share ${email}.`,
+        summary: `${contacts.length} contacts share ${email}.${provenanceSummary(contacts)}`,
         recommendation: "Merge the duplicates so engagement history and routing stay coherent.",
       });
       operations.push({
@@ -433,7 +454,7 @@ export const duplicateOpenDealRule: GtmAuditRule = {
         severity: "warning",
         summary: `${deals.length} open deals named "${anchor.name}"${
           anchor.accountId ? " on the same account" : ""
-        }: ${deals.map((deal) => deal.id).join(", ")}.`,
+        }: ${deals.map((deal) => deal.id).join(", ")}.${provenanceSummary(deals)}`,
         recommendation:
           "Keep one deal, archive the copies, and fix the integration that is re-creating them.",
       });

package/src/types.ts

@@ -34,6 +34,7 @@ export type GtmEvidenceSourceSystem =
   | "manual"
   | "csv"
   | "mock"
+  | "web"
   | "unknown";
 
 export type PatchOperationType =
@@ -141,11 +142,26 @@ export type CanonicalUser = {
   active?: boolean;
 };
 
+/**
+ * Who created a record, per the provider's read-only record-source fields
+ * (HubSpot: hs_object_source / _label / _id). Populated on read; used to
+ * attribute duplicate findings to the writer that produced them.
+ */
+export type RecordProvenance = {
+  /** Provider source code, e.g. INTEGRATION, API, CRM_UI, IMPORT, FORM. */
+  source?: string;
+  /** Human label, e.g. an integration's name. */
+  sourceLabel?: string;
+  /** Provider-side id of the source (e.g. app id, import id). */
+  sourceId?: string;
+};
+
 export type CanonicalAccount = {
   id: string;
   provider?: CrmProvider;
   crmId?: string;
   identities?: ProviderIdentity[];
+  provenance?: RecordProvenance;
   name: string;
   domain?: string;
   industry?: string;
@@ -163,6 +179,7 @@ export type CanonicalContact = {
   provider?: CrmProvider;
   crmId?: string;
   identities?: ProviderIdentity[];
+  provenance?: RecordProvenance;
   accountId?: string;
   firstName?: string;
   lastName?: string;
@@ -181,6 +198,7 @@ export type CanonicalDeal = {
   provider?: CrmProvider;
   crmId?: string;
   identities?: ProviderIdentity[];
+  provenance?: RecordProvenance;
   accountId?: string;
   ownerId?: string;
   name: string;