fullstackgtm 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md).
 
+## [0.15.0] — 2026-06-11
+
+The Prevent layer: stop creating duplicates, and name the writer that does.
+
+### Added
+
+- **`fullstackgtm resolve <account|contact|deal>`** — the create gate.
+  Deterministic verdicts (exists / ambiguous / safe_to_create) with matches
+  and reasons, using the same identity keys as the audit/merge engines:
+  normalized account domain, contact email, open-deal key. Names alone are
+  never identity (ambiguous, with candidates). Gate-shaped exit codes for
+  scripts: 0 = safe to create, 2 = match found, 1 = error. Exposed as
+  `resolveRecord()` and MCP `fullstackgtm_resolve`.
+- **Record provenance** (`RecordProvenance` on accounts/contacts/deals):
+  HubSpot snapshots capture the read-only `hs_object_source`,
+  `hs_object_source_label`, `hs_object_source_id` fields, and the three
+  duplicate rules append writer attribution to findings — "Created by:
+  Gojiberry (app-123) ×2, CRM_UI" — so recurring dupes are fixed at the
+  faucet. Provenance is exempt from merge conflicts and diff drift, and
+  records created by the CLI's own `create:` path stamp
+  `hs_object_source_detail_2` (best-effort).
+
 ## [0.14.1] — 2026-06-11
 
 Fixes from the 0.14.0 journey verification (4 agents, 21 checks).

package/README.md

@@ -74,6 +74,20 @@ for t in transcripts/*; do fullstackgtm call parse --transcript "$t" --ndjson --
 
 The boundary that remains: Slack/Notion/warehouse sinks are *your* pipeline, composed around the JSON — and your rubrics and keys stay yours.
 
+## The create gate: no new dupes
+
+Detection cleans up yesterday's duplicates; the **resolve gate** prevents tomorrow's. Before any writer — a sync job, a webhook handler, an agent, your own script — creates a record, ask the gate:
+
+```bash
+fullstackgtm resolve contact --email jane@acme.com --input snap.json   # exit 0 = safe to create
+fullstackgtm resolve account --domain acme.com --provider hubspot      # exit 2 = exists/ambiguous: do NOT create
+fullstackgtm resolve deal --name "Acme Expansion" --account-id 123 --input snap.json
+```
+
+Identity keys match the audit/merge engines exactly: account domain (normalized), contact email, and the open-deal key (account + normalized name). Names alone are never identity — they return `ambiguous` with the candidates, not a guess. Exit codes are gate-shaped for scripts: `0` safe to create, `2` match found, `1` error. For high-volume writers, pair it with a cron-refreshed snapshot file rather than a live `--provider` fetch per call. Also exposed as `resolveRecord()` and the MCP tool `fullstackgtm_resolve`.
+
+**Provenance attribution** closes the loop on recurring dupes: snapshots now capture each record's source (HubSpot's read-only `hs_object_source*` fields), and duplicate findings name the writer — `"3 accounts share acme.com … Created by: Gojiberry (app-123) ×2, CRM_UI"` — so you fix the integration, not just the records. Records created by this CLI stamp their own provenance (`hs_object_source_detail_2`, best-effort).
+
 ## From findings to fixes: the suggest chain
 
 Most placeholder answers are already derivable from your own CRM data. `suggest` computes them deterministically — account-name matching cross-checked against contact associations — with a confidence level and a written reason per operation, so you (or an agent) approve evidence, not guesses:

package/dist/cli.js

@@ -19,6 +19,7 @@ import { builtinAuditRules } from "./rules.js";
 import { sampleSnapshot } from "./sampleData.js";
 import { normalizeTranscript, parseCall, suggestCallDeal } from "./calls.js";
 import { DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
+import { resolveRecord } from "./resolve.js";
 import { suggestValues } from "./suggest.js";
 function usage() {
     return `FullStackGTM — audit GTM data across providers, propose reviewable patch plans,
@@ -51,6 +52,9 @@ Usage:
                                                ANTHROPIC_API_KEY/OPENAI_API_KEY, or \`login anthropic|openai\`);
                                                --deterministic uses the free keyword baseline. Then link the call
                                                to its deal and propose governed next-step writes.
+  fullstackgtm resolve <account|contact|deal> [--name N] [--domain D] [--email E] [--account-id A] [source options] [--json]
+                                               the create gate: exit 0 = safe to create, exit 2 = match
+                                               found (exists/ambiguous) — call before ANY record creation
   fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
                                                derive values for requires_human_* placeholders
                                                from snapshot evidence, with confidence + reasons
@@ -711,6 +715,38 @@ function buildCallPlan(parsed, deal, proposed, current, extraNextSteps) {
         operations,
     };
 }
+/**
+ * The resolve gate: exit 0 = safe to create, exit 2 = match found (exists or
+ * ambiguous — do NOT blind-create), exit 1 = error. Built for sync jobs and
+ * webhook handlers to call before any record creation.
+ */
+async function resolveCommand(args) {
+    const [objectType, ...rest] = args;
+    if (!objectType || !["account", "contact", "deal"].includes(objectType)) {
+        throw new Error("Usage: fullstackgtm resolve <account|contact|deal> [--name N] [--domain D] [--email E] [--account-id A] [source options] [--json]");
+    }
+    const candidate = {
+        objectType: objectType,
+        name: option(rest, "--name") ?? undefined,
+        domain: option(rest, "--domain") ?? undefined,
+        email: option(rest, "--email") ?? undefined,
+        accountId: option(rest, "--account-id") ?? undefined,
+    };
+    const snapshot = await readSnapshot(rest);
+    const result = resolveRecord(snapshot, candidate);
+    if (rest.includes("--json")) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        const marker = result.verdict === "safe_to_create" ? "✓" : result.verdict === "exists" ? "=" : "?";
+        console.log(`${marker} [${result.verdict}] ${result.reason}`);
+        for (const m of result.matches) {
+            console.log(`    ${m.id} "${m.name}" — matched by ${m.matchedBy}: ${m.detail}`);
+        }
+    }
+    if (result.verdict !== "safe_to_create")
+        process.exitCode = 2;
+}
 async function suggest(args) {
     const planId = option(args, "--plan-id");
     const planPath = option(args, "--plan");
@@ -1456,6 +1492,10 @@ export async function runCli(argv) {
         await callCommand(args);
         return;
     }
+    if (command === "resolve") {
+        await resolveCommand(args);
+        return;
+    }
     if (command === "profiles") {
         profilesCommand(args);
         return;

package/dist/connectors/hubspot.js

@@ -84,7 +84,10 @@ export function createHubspotConnector(options) {
             email: stringOrUndefined(owner.email),
             active: owner.archived !== true,
         }));
-        const companyProperties = mappedFields(mappings, "accounts", HUBSPOT_DEFAULT_FIELD_MAPPINGS.accounts).join(",");
+        // Read-only record-source fields power duplicate-finding attribution
+        // ("all five created by integration X") — see RecordProvenance.
+        const PROVENANCE_PROPERTIES = "hs_object_source,hs_object_source_label,hs_object_source_id";
+        const companyProperties = `${mappedFields(mappings, "accounts", HUBSPOT_DEFAULT_FIELD_MAPPINGS.accounts).join(",")},${PROVENANCE_PROPERTIES}`;
         const companies = await fetchObjects("companies", companyProperties, false);
         const accounts = companies
             .filter((company) => company.id)
@@ -101,11 +104,12 @@ export function createHubspotConnector(options) {
                 employeeCount: numberOrUndefined(readMapped(props, "accounts", "employeeCount", "numberofemployees")),
                 annualRevenue: numberOrUndefined(readMapped(props, "accounts", "annualRevenue", "annualrevenue")),
                 ownerId: stringOrUndefined(readMapped(props, "accounts", "ownerId", "hubspot_owner_id")),
+                provenance: provenanceFrom(props),
                 lastSyncAt: stringOrUndefined(company.updatedAt),
                 raw: company,
             };
         });
-        const contactProperties = mappedFields(mappings, "contacts", HUBSPOT_DEFAULT_FIELD_MAPPINGS.contacts).join(",");
+        const contactProperties = `${mappedFields(mappings, "contacts", HUBSPOT_DEFAULT_FIELD_MAPPINGS.contacts).join(",")},${PROVENANCE_PROPERTIES}`;
         const hubspotContacts = await fetchObjects("contacts", contactProperties, true);
         const contacts = hubspotContacts
             .filter((contact) => contact.id)
@@ -124,11 +128,12 @@ export function createHubspotConnector(options) {
                 phone: stringOrUndefined(readMapped(props, "contacts", "phone", "phone")),
                 title: stringOrUndefined(readMapped(props, "contacts", "title", "jobtitle")),
                 ownerId: stringOrUndefined(readMapped(props, "contacts", "ownerId", "hubspot_owner_id")),
+                provenance: provenanceFrom(props),
                 lastSyncAt: stringOrUndefined(contact.updatedAt),
                 raw: contact,
             };
         });
-        const dealProperties = mappedFields(mappings, "deals", HUBSPOT_DEFAULT_FIELD_MAPPINGS.deals).join(",");
+        const dealProperties = `${mappedFields(mappings, "deals", HUBSPOT_DEFAULT_FIELD_MAPPINGS.deals).join(",")},${PROVENANCE_PROPERTIES}`;
         const hubspotDeals = await fetchObjects("deals", dealProperties, true);
         const deals = hubspotDeals
             .filter((deal) => deal.id)
@@ -152,6 +157,7 @@ export function createHubspotConnector(options) {
                 identities: [{ provider: "hubspot", externalId: String(deal.id) }],
                 accountId: companyId ? String(companyId) : undefined,
                 ownerId: stringOrUndefined(readMapped(props, "deals", "ownerId", "hubspot_owner_id")),
+                provenance: provenanceFrom(props),
                 name: stringOrFallback(readMapped(props, "deals", "name", "dealname"), "Untitled Deal"),
                 amount: numberOrUndefined(readMapped(props, "deals", "amount", "amount")),
                 stage,
@@ -323,10 +329,23 @@ export function createHubspotConnector(options) {
                     createdCompaniesByName.set(nameKey, companyId);
                 }
                 else {
-                    const created = await request(`/crm/v3/objects/companies`, {
-                        method: "POST",
-                        body: JSON.stringify({ properties: { name } }),
-                    });
+                    let created;
+                    try {
+                        created = await request(`/crm/v3/objects/companies`, {
+                            method: "POST",
+                            body: JSON.stringify({
+                                properties: { name, hs_object_source_detail_2: "fullstackgtm create: operation" },
+                            }),
+                        });
+                    }
+                    catch {
+                        // Some portals reject writes to source-detail properties — the
+                        // provenance stamp is best-effort, the create is not.
+                        created = await request(`/crm/v3/objects/companies`, {
+                            method: "POST",
+                            body: JSON.stringify({ properties: { name } }),
+                        });
+                    }
                     companyId = String(created.id);
                     createdCompanyName = name;
                     createdCompaniesByName.set(nameKey, companyId);
@@ -394,6 +413,34 @@ export function createHubspotConnector(options) {
         catch {
             // fall through to create
         }
+        // A live CRM often already carries a human-created follow-up for the same
+        // record (a previous partial run, or a rep's own task). Creating another
+        // on top is duplicate noise — skip when the object already has an open
+        // task, regardless of who created it. Fail-open: a lookup hiccup must
+        // not block the apply.
+        try {
+            const objectPath = OBJECT_PATHS[operation.objectType];
+            const assoc = await request(`/crm/v4/objects/${objectPath}/${encodeURIComponent(operation.objectId)}/associations/tasks?limit=20`);
+            const taskIds = (assoc?.results ?? [])
+                .map((row) => String(row.toObjectId ?? ""))
+                .filter(Boolean)
+                .slice(0, 10);
+            for (const taskId of taskIds) {
+                const existingTask = await request(`/crm/v3/objects/tasks/${encodeURIComponent(taskId)}?properties=hs_task_status`);
+                const status = String(existingTask?.properties?.hs_task_status ?? "");
+                if (status !== "COMPLETED" && status !== "DELETED") {
+                    return {
+                        operationId: operation.id,
+                        status: "skipped",
+                        detail: `An open task (task ${taskId}) already exists on ${operation.objectType}/${operation.objectId}; not creating a duplicate follow-up.`,
+                        providerData: { id: taskId, existing: true },
+                    };
+                }
+            }
+        }
+        catch {
+            // fall through to create
+        }
         const body = `${String(operation.afterValue ?? operation.reason ?? "")}\n\n[${token}]`;
         const response = await request(`/crm/v3/objects/tasks`, {
             method: "POST",
@@ -567,6 +614,14 @@ export function createHubspotConnector(options) {
         readField,
     };
 }
+function provenanceFrom(props) {
+    const source = stringOrUndefined(props.hs_object_source);
+    const sourceLabel = stringOrUndefined(props.hs_object_source_label);
+    const sourceId = stringOrUndefined(props.hs_object_source_id);
+    if (!source && !sourceLabel && !sourceId)
+        return undefined;
+    return { source, sourceLabel, sourceId };
+}
 function stringOrUndefined(value) {
     if (value === undefined || value === null || value === "")
         return undefined;

package/dist/diff.js

@@ -4,7 +4,7 @@
  * appeared, what disappeared, what changed — and whether hygiene regressed.
  */
 // Fields that change on every sync without semantic meaning.
-const IGNORED_FIELDS = new Set(["raw", "lastSyncAt", "identities"]);
+const IGNORED_FIELDS = new Set(["raw", "lastSyncAt", "identities", "provenance"]);
 function labelOf(record) {
     return record.name ?? record.email ?? record.id;
 }

package/dist/index.d.ts

@@ -14,9 +14,10 @@ export { createFilePlanStore, type PlanStore, type StoredPlan } from "./planStor
 export { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
 export { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./report.ts";
 export { HUBSPOT_DEFAULT_FIELD_MAPPINGS, SALESFORCE_DEFAULT_FIELD_MAPPINGS, mappedField, mappedFields, normalizeFieldMappings, readMappedValue, type CrmObjectType, type FieldMappings, } from "./mappings.ts";
-export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, requiresHumanInput, staleDealRule, } from "./rules.ts";
+export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, provenanceSummary, requiresHumanInput, staleDealRule, } from "./rules.ts";
 export { extractCallInsights, normalizeTranscript, parseCall, parseTranscript, suggestCallDeal, summarizeInsights, type CallDealSuggestion, type CallInsightType, type ExtractedCallInsight, type ParsedCall, type ParsedTranscriptSegment, } from "./calls.ts";
 export { sampleSnapshot } from "./sampleData.ts";
 export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, type CallScorecard, type LlmCredential, type LlmExtractedInsight, type LlmProvider, type Rubric, type ScoredDimension, } from "./llm.ts";
+export { resolveRecord, type ResolveCandidate, type ResolveMatch, type ResolveResult } from "./resolve.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export type { ApprovalStatus, AuditFinding, AuditFindingSeverity, CanonicalAccount, CanonicalActivity, CanonicalContact, CanonicalDeal, CanonicalGtmSnapshot, CanonicalUser, CrmProvider, GtmAuditRule, GtmConnector, GtmEvidence, GtmEvidenceSourceSystem, GtmObjectType, GtmPolicy, GtmRuleContext, GtmRuleResult, GtmSnapshotIndex, PatchOperation, PatchOperationResult, PatchOperationType, PatchPlan, PatchPlanRun, PatchPlanRunStatus, PatchVerification, PipelineFinding, PipelineFindingStatus, PipelineFindingType, ProviderIdentity, RiskLevel, SourceFreshness, } from "./types.ts";

package/dist/index.js

@@ -14,8 +14,9 @@ export { createFilePlanStore } from "./planStore.js";
 export { formatPatchPlanRun, patchPlanToMarkdown } from "./format.js";
 export { auditReportToHtml, auditReportToMarkdown } from "./report.js";
 export { HUBSPOT_DEFAULT_FIELD_MAPPINGS, SALESFORCE_DEFAULT_FIELD_MAPPINGS, mappedField, mappedFields, normalizeFieldMappings, readMappedValue, } from "./mappings.js";
-export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, requiresHumanInput, staleDealRule, } from "./rules.js";
+export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, provenanceSummary, requiresHumanInput, staleDealRule, } from "./rules.js";
 export { extractCallInsights, normalizeTranscript, parseCall, parseTranscript, suggestCallDeal, summarizeInsights, } from "./calls.js";
 export { sampleSnapshot } from "./sampleData.js";
 export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
+export { resolveRecord } from "./resolve.js";
 export { suggestValues } from "./suggest.js";

package/dist/mcp.js

@@ -47,6 +47,7 @@ import { builtinAuditRules } from "./rules.js";
 import { sampleSnapshot } from "./sampleData.js";
 import { normalizeTranscript, parseCall } from "./calls.js";
 import { extractInsightsLlm, resolveLlmCredential } from "./llm.js";
+import { resolveRecord } from "./resolve.js";
 import { suggestValues } from "./suggest.js";
 function content(value) {
     return {
@@ -197,6 +198,25 @@ export async function startMcpServer() {
         }
         return content(parseCall(raw, { title, sourceSystem: source }));
     });
+    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", {
         title: "List Audit Rules",
         description: "List the built-in deterministic audit rules with ids and descriptions.",

package/dist/merge.js

@@ -1,5 +1,5 @@
 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) {
     if (!domain)

package/dist/resolve.d.ts

@@ -0,0 +1,37 @@
+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 declare function resolveRecord(snapshot: CanonicalGtmSnapshot, candidate: ResolveCandidate): ResolveResult;

package/dist/resolve.js

@@ -0,0 +1,107 @@
+import { normalizeDomain } from "./merge.js";
+export function resolveRecord(snapshot, candidate) {
+    if (candidate.objectType === "account")
+        return resolveAccount(snapshot, candidate);
+    if (candidate.objectType === "contact")
+        return resolveContact(snapshot, candidate);
+    return resolveDeal(snapshot, candidate);
+}
+function resolveAccount(snapshot, c) {
+    const base = { objectType: "account" };
+    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, c) {
+    const base = { objectType: "contact" };
+    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, c) {
+    const base = { objectType: "deal" };
+    if (!c.name) {
+        return { ...base, verdict: "ambiguous", matches: [], reason: "Supply --name (and ideally --account-id) to resolve a deal." };
+    }
+    const key = `${c.accountId ?? "unlinked"}:${normalizeName(c.name)}`;
+    const open = snapshot.deals.filter((d) => d.isClosed !== true && d.isWon !== true);
+    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 ${c.accountId ? `account ${c.accountId}` : "no account"}`));
+    if (matches.length > 0) {
+        return {
+            ...base,
+            verdict: "exists",
+            matches,
+            reason: `${matches.length} open deal(s) already match "${c.name}" on ${c.accountId ? `account ${c.accountId}` : "unlinked"} — creating another would double-count pipeline. Update the existing deal.`,
+        };
+    }
+    const closedSameName = snapshot.deals.filter((d) => (d.isClosed === true || d.isWon === true) && normalizeName(d.name) === normalizeName(c.name));
+    return {
+        ...base,
+        verdict: "safe_to_create",
+        matches: [],
+        reason: closedSameName.length > 0
+            ? `No open deal matches; ${closedSameName.length} closed deal(s) share the name (a re-open/renewal may be intended). Safe to create.`
+            : `No open deal matches "${c.name}". Safe to create.`,
+    };
+}
+function contactName(row) {
+    return [row.firstName, row.lastName].filter(Boolean).join(" ") || "(unnamed)";
+}
+function normalizeName(value) {
+    return value.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function match(id, name, matchedBy, detail) {
+    return { id, name, matchedBy, detail };
+}

package/dist/rules.d.ts

@@ -6,6 +6,18 @@ import type { CanonicalGtmSnapshot, GtmAuditRule, GtmSnapshotIndex } from "./typ
  */
 export declare const REQUIRES_HUMAN_PREFIX = "requires_human_";
 export declare function requiresHumanInput(value: unknown): boolean;
+/**
+ * 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 declare function provenanceSummary(records: Array<{
+    provenance?: {
+        source?: string;
+        sourceLabel?: string;
+        sourceId?: string;
+    };
+}>): string;
 export declare function auditFindingId(ruleId: string, objectId: string): string;
 export declare function patchOperationId(ruleId: string, objectId: string): string;
 export declare function stableHash(value: string): string;

package/dist/rules.js

@@ -8,6 +8,28 @@ export const REQUIRES_HUMAN_PREFIX = "requires_human_";
 export function requiresHumanInput(value) {
     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) {
+    const counts = new Map();
+    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, objectId) {
     return `finding_${stableHash(`${ruleId}:${objectId}`)}`;
 }
@@ -326,7 +348,7 @@ export const duplicateAccountDomainRule = {
                 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({
@@ -363,7 +385,7 @@ export const duplicateContactEmailRule = {
                 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({
@@ -410,7 +432,7 @@ export const duplicateOpenDealRule = {
                 ruleId: "duplicate-open-deal",
                 title: "Open deals duplicate the same opportunity",
                 severity: "warning",
-                summary: `${deals.length} open deals named "${anchor.name}"${anchor.accountId ? " on the same account" : ""}: ${deals.map((deal) => deal.id).join(", ")}.`,
+                summary: `${deals.length} open deals named "${anchor.name}"${anchor.accountId ? " on the same account" : ""}: ${deals.map((deal) => deal.id).join(", ")}.${provenanceSummary(deals)}`,
                 recommendation: "Keep one deal, archive the copies, and fix the integration that is re-creating them.",
             });
             operations.push({

package/dist/types.d.ts

@@ -83,11 +83,25 @@ export type CanonicalUser = {
     title?: string;
     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;
@@ -104,6 +118,7 @@ export type CanonicalContact = {
     provider?: CrmProvider;
     crmId?: string;
     identities?: ProviderIdentity[];
+    provenance?: RecordProvenance;
     accountId?: string;
     firstName?: string;
     lastName?: string;
@@ -121,6 +136,7 @@ export type CanonicalDeal = {
     provider?: CrmProvider;
     crmId?: string;
     identities?: ProviderIdentity[];
+    provenance?: RecordProvenance;
     accountId?: string;
     ownerId?: string;
     name: string;

package/docs/crm-health-lifecycle.md

@@ -41,12 +41,11 @@ fix the faucet instead of mopping the puddle.
   a unique match, refuse on ambiguity, create only on a confirmed miss.
   HubSpot's search API is eventually consistent (~5–10s), so same-run
   creations are deduped in memory, not via search.
-- A standalone **`resolve` gate** (planned, 0.13): given a candidate
-  record, return existing match(es) or "safe to create" — for the CLI, the
-  library, MCP, and any external writer (sync jobs, agents, webhook
-  handlers). Identity keys are the ones the package already uses:
-  contact email, normalized account domain, and the open-deal key
-  (account + normalized name).
+- The **`resolve` gate** (shipped 0.15): `fullstackgtm resolve
+  <account|contact|deal>` returns exists/ambiguous/safe_to_create with
+  matches and reasons; exit 0 = safe, exit 2 = do not create. Same identity
+  keys as the audit/merge engines. Also `resolveRecord()` and MCP
+  `fullstackgtm_resolve`.
 - **Stamp provenance on our own creates** (HubSpot allows integrations to
   set `hs_object_source_detail_2/3` at create time).
 - Recommend native config in `doctor`/audit: Salesforce duplicate rules
@@ -61,10 +60,10 @@ fix the faucet instead of mopping the puddle.
   (ruleId, objectId).
 - **The nightly watch recipe** ("CRM CI"): scheduled
   `snapshot → audit → diff` against yesterday's snapshot, alert on exit 2.
-- **Attribution** (planned, 0.13): capture HubSpot's read-only
-  `hs_object_source`, `hs_object_source_label`, `hs_object_source_id` into
-  the canonical model so duplicate findings can say *"all five created by
-  integration X"*. The fix for recurring dupes is upstream, in the writer.
+- **Attribution** (shipped 0.15): snapshots capture HubSpot's read-only
+  `hs_object_source*` into `RecordProvenance`; duplicate findings append
+  *"Created by: …"* naming the writer(s). The fix for recurring dupes is
+  upstream, in the writer.
 - Incremental reads (`snapshot --since`) exist for all three connectors;
   caveats: HubSpot deltas carry no associations and cap at 10k per object,
   Stripe deltas catch creations only.
@@ -131,5 +130,6 @@ Lessons from auditing our own apply path:
 | --- | --- |
 | 0.11.1 | Fix our own faucet: resolve-first `create:` + plan-scoped dedup, HubSpot association-aware CAS for `link_record`, domain normalization in `duplicate-account-domain`, `create_task` idempotency token |
 | 0.12 (shipped) | `merge_records` (HubSpot contacts/companies/deals) + survivor suggestions capped at low confidence; the three duplicate rules emit governed merges instead of review tasks |
-| 0.13 | `resolve` gate (CLI/lib/MCP), provenance capture + attribution in findings, prevention-posture checks |
+| 0.15 (shipped) | `resolve` gate (CLI/lib/MCP, gate exit codes), provenance capture (`hs_object_source*` → `RecordProvenance`) + attribution in duplicate findings, self-stamped creates |
+| 0.16 | prevention-posture checks (native duplicate rules active? unique-value properties defined?) · live targeted resolve lookups |
 | docs | The nightly watch recipe (existing flags, documented as CRM CI) |

package/llms.txt

@@ -18,6 +18,10 @@ at/above `--fail-on`.
 - [CRM-health lifecycle](https://github.com/fullstackgtm/core/blob/main/docs/crm-health-lifecycle.md): the Prevent → Detect → Remediate → Verify/Attribute model; no-new-dupes design
 - [CHANGELOG](https://github.com/fullstackgtm/core/blob/main/CHANGELOG.md): release history
 
+`fullstackgtm resolve <type>` is the create gate: exit 0 = safe to create,
+exit 2 = exists/ambiguous (never blind-create); duplicate findings carry
+"Created by:" writer attribution when the provider exposes record source.
+
 ## Key invariants (calls)
 
 `fullstackgtm call parse` defaults to LLM extraction (BYO Anthropic/OpenAI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM",

package/src/cli.ts

@@ -50,6 +50,7 @@ import {
   type CallScorecard,
   type LlmProvider,
 } from "./llm.ts";
+import { resolveRecord, type ResolveCandidate } from "./resolve.ts";
 import { suggestValues, type ValueSuggestion } from "./suggest.ts";
 import type { FieldMappings } from "./mappings.ts";
 import type {
@@ -90,6 +91,9 @@ Usage:
                                                ANTHROPIC_API_KEY/OPENAI_API_KEY, or \`login anthropic|openai\`);
                                                --deterministic uses the free keyword baseline. Then link the call
                                                to its deal and propose governed next-step writes.
+  fullstackgtm resolve <account|contact|deal> [--name N] [--domain D] [--email E] [--account-id A] [source options] [--json]
+                                               the create gate: exit 0 = safe to create, exit 2 = match
+                                               found (exists/ambiguous) — call before ANY record creation
   fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
                                                derive values for requires_human_* placeholders
                                                from snapshot evidence, with confidence + reasons
@@ -797,6 +801,37 @@ function buildCallPlan(
   };
 }
 
+/**
+ * The resolve gate: exit 0 = safe to create, exit 2 = match found (exists or
+ * ambiguous — do NOT blind-create), exit 1 = error. Built for sync jobs and
+ * webhook handlers to call before any record creation.
+ */
+async function resolveCommand(args: string[]) {
+  const [objectType, ...rest] = args;
+  if (!objectType || !["account", "contact", "deal"].includes(objectType)) {
+    throw new Error("Usage: fullstackgtm resolve <account|contact|deal> [--name N] [--domain D] [--email E] [--account-id A] [source options] [--json]");
+  }
+  const candidate: ResolveCandidate = {
+    objectType: objectType as ResolveCandidate["objectType"],
+    name: option(rest, "--name") ?? undefined,
+    domain: option(rest, "--domain") ?? undefined,
+    email: option(rest, "--email") ?? undefined,
+    accountId: option(rest, "--account-id") ?? undefined,
+  };
+  const snapshot = await readSnapshot(rest);
+  const result = resolveRecord(snapshot, candidate);
+  if (rest.includes("--json")) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    const marker = result.verdict === "safe_to_create" ? "✓" : result.verdict === "exists" ? "=" : "?";
+    console.log(`${marker} [${result.verdict}] ${result.reason}`);
+    for (const m of result.matches) {
+      console.log(`    ${m.id} "${m.name}" — matched by ${m.matchedBy}: ${m.detail}`);
+    }
+  }
+  if (result.verdict !== "safe_to_create") process.exitCode = 2;
+}
+
 async function suggest(args: string[]) {
   const planId = option(args, "--plan-id");
   const planPath = option(args, "--plan");
@@ -1626,6 +1661,10 @@ export async function runCli(argv: string[]) {
     await callCommand(args);
     return;
   }
+  if (command === "resolve") {
+    await resolveCommand(args);
+    return;
+  }
   if (command === "profiles") {
     profilesCommand(args);
     return;

package/src/connectors/hubspot.ts

@@ -10,6 +10,7 @@ import type {
   CanonicalAccount,
   CanonicalContact,
   CanonicalDeal,
+  RecordProvenance,
   CanonicalGtmSnapshot,
   CanonicalUser,
   GtmConnector,
@@ -125,11 +126,14 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
         active: owner.archived !== true,
       }));
 
-    const companyProperties = mappedFields(
+    // Read-only record-source fields power duplicate-finding attribution
+    // ("all five created by integration X") — see RecordProvenance.
+    const PROVENANCE_PROPERTIES = "hs_object_source,hs_object_source_label,hs_object_source_id";
+    const companyProperties = `${mappedFields(
       mappings,
       "accounts",
       HUBSPOT_DEFAULT_FIELD_MAPPINGS.accounts,
-    ).join(",");
+    ).join(",")},${PROVENANCE_PROPERTIES}`;
     const companies = await fetchObjects("companies", companyProperties, false);
     const accounts: CanonicalAccount[] = companies
       .filter((company) => company.id)
@@ -155,16 +159,17 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
           ownerId: stringOrUndefined(
             readMapped(props, "accounts", "ownerId", "hubspot_owner_id"),
           ),
+          provenance: provenanceFrom(props),
           lastSyncAt: stringOrUndefined(company.updatedAt),
           raw: company,
         };
       });
 
-    const contactProperties = mappedFields(
+    const contactProperties = `${mappedFields(
       mappings,
       "contacts",
       HUBSPOT_DEFAULT_FIELD_MAPPINGS.contacts,
-    ).join(",");
+    ).join(",")},${PROVENANCE_PROPERTIES}`;
     const hubspotContacts = await fetchObjects("contacts", contactProperties, true);
     const contacts: CanonicalContact[] = hubspotContacts
       .filter((contact) => contact.id)
@@ -185,16 +190,17 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
           ownerId: stringOrUndefined(
             readMapped(props, "contacts", "ownerId", "hubspot_owner_id"),
           ),
+          provenance: provenanceFrom(props),
           lastSyncAt: stringOrUndefined(contact.updatedAt),
           raw: contact,
         };
       });
 
-    const dealProperties = mappedFields(
+    const dealProperties = `${mappedFields(
       mappings,
       "deals",
       HUBSPOT_DEFAULT_FIELD_MAPPINGS.deals,
-    ).join(",");
+    ).join(",")},${PROVENANCE_PROPERTIES}`;
     const hubspotDeals = await fetchObjects("deals", dealProperties, true);
     const deals: CanonicalDeal[] = hubspotDeals
       .filter((deal) => deal.id)
@@ -220,6 +226,7 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
           identities: [{ provider: "hubspot", externalId: String(deal.id) }],
           accountId: companyId ? String(companyId) : undefined,
           ownerId: stringOrUndefined(readMapped(props, "deals", "ownerId", "hubspot_owner_id")),
+          provenance: provenanceFrom(props),
           name: stringOrFallback(readMapped(props, "deals", "name", "dealname"), "Untitled Deal"),
           amount: numberOrUndefined(readMapped(props, "deals", "amount", "amount")),
           stage,
@@ -419,10 +426,22 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
           resolvedExisting = true;
           createdCompaniesByName.set(nameKey, companyId);
         } else {
-          const created = await request(`/crm/v3/objects/companies`, {
-            method: "POST",
-            body: JSON.stringify({ properties: { name } }),
-          });
+          let created;
+          try {
+            created = await request(`/crm/v3/objects/companies`, {
+              method: "POST",
+              body: JSON.stringify({
+                properties: { name, hs_object_source_detail_2: "fullstackgtm create: operation" },
+              }),
+            });
+          } catch {
+            // Some portals reject writes to source-detail properties — the
+            // provenance stamp is best-effort, the create is not.
+            created = await request(`/crm/v3/objects/companies`, {
+              method: "POST",
+              body: JSON.stringify({ properties: { name } }),
+            });
+          }
           companyId = String(created.id);
           createdCompanyName = name;
           createdCompaniesByName.set(nameKey, companyId);
@@ -494,6 +513,37 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     } catch {
       // fall through to create
     }
+    // A live CRM often already carries a human-created follow-up for the same
+    // record (a previous partial run, or a rep's own task). Creating another
+    // on top is duplicate noise — skip when the object already has an open
+    // task, regardless of who created it. Fail-open: a lookup hiccup must
+    // not block the apply.
+    try {
+      const objectPath = OBJECT_PATHS[operation.objectType];
+      const assoc = await request(
+        `/crm/v4/objects/${objectPath}/${encodeURIComponent(operation.objectId)}/associations/tasks?limit=20`,
+      );
+      const taskIds = ((assoc?.results ?? []) as Array<{ toObjectId?: number | string }>)
+        .map((row) => String(row.toObjectId ?? ""))
+        .filter(Boolean)
+        .slice(0, 10);
+      for (const taskId of taskIds) {
+        const existingTask = await request(
+          `/crm/v3/objects/tasks/${encodeURIComponent(taskId)}?properties=hs_task_status`,
+        );
+        const status = String(existingTask?.properties?.hs_task_status ?? "");
+        if (status !== "COMPLETED" && status !== "DELETED") {
+          return {
+            operationId: operation.id,
+            status: "skipped",
+            detail: `An open task (task ${taskId}) already exists on ${operation.objectType}/${operation.objectId}; not creating a duplicate follow-up.`,
+            providerData: { id: taskId, existing: true },
+          };
+        }
+      }
+    } catch {
+      // fall through to create
+    }
     const body = `${String(operation.afterValue ?? operation.reason ?? "")}\n\n[${token}]`;
     const response = await request(`/crm/v3/objects/tasks`, {
       method: "POST",
@@ -686,6 +736,14 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
   };
 }
 
+function provenanceFrom(props: Record<string, unknown>): RecordProvenance | undefined {
+  const source = stringOrUndefined(props.hs_object_source);
+  const sourceLabel = stringOrUndefined(props.hs_object_source_label);
+  const sourceId = stringOrUndefined(props.hs_object_source_id);
+  if (!source && !sourceLabel && !sourceId) return undefined;
+  return { source, sourceLabel, sourceId };
+}
+
 function stringOrUndefined(value: unknown): string | undefined {
   if (value === undefined || value === null || value === "") return undefined;
   return String(value);

package/src/diff.ts

@@ -7,7 +7,7 @@ import type { AuditFinding, CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
  */
 
 // Fields that change on every sync without semantic meaning.
-const IGNORED_FIELDS = new Set(["raw", "lastSyncAt", "identities"]);
+const IGNORED_FIELDS = new Set(["raw", "lastSyncAt", "identities", "provenance"]);
 
 export type FieldChange = { field: string; before: unknown; after: unknown };
 

package/src/index.ts

@@ -95,6 +95,7 @@ export {
   orphanAccountRule,
   pastCloseDateRule,
   patchOperationId,
+  provenanceSummary,
   requiresHumanInput,
   staleDealRule,
 } from "./rules.ts";
@@ -128,6 +129,7 @@ export {
   type Rubric,
   type ScoredDimension,
 } from "./llm.ts";
+export { resolveRecord, type ResolveCandidate, type ResolveMatch, type ResolveResult } from "./resolve.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export type {
   ApprovalStatus,

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,157 @@
+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 key = `${c.accountId ?? "unlinked"}:${normalizeName(c.name)}`;
+  const open = snapshot.deals.filter((d) => d.isClosed !== true && d.isWon !== true);
+  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 ${c.accountId ? `account ${c.accountId}` : "no account"}`));
+  if (matches.length > 0) {
+    return {
+      ...base,
+      verdict: "exists",
+      matches,
+      reason: `${matches.length} open deal(s) already match "${c.name}" on ${c.accountId ? `account ${c.accountId}` : "unlinked"} — creating another would double-count pipeline. Update the existing deal.`,
+    };
+  }
+  const closedSameName = snapshot.deals.filter(
+    (d) => (d.isClosed === true || d.isWon === true) && normalizeName(d.name) === normalizeName(c.name!),
+  );
+  return {
+    ...base,
+    verdict: "safe_to_create",
+    matches: [],
+    reason: closedSameName.length > 0
+      ? `No open deal matches; ${closedSameName.length} closed deal(s) share the name (a re-open/renewal may be intended). Safe to create.`
+      : `No open deal matches "${c.name}". 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

@@ -141,11 +141,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 +178,7 @@ export type CanonicalContact = {
   provider?: CrmProvider;
   crmId?: string;
   identities?: ProviderIdentity[];
+  provenance?: RecordProvenance;
   accountId?: string;
   firstName?: string;
   lastName?: string;
@@ -181,6 +197,7 @@ export type CanonicalDeal = {
   provider?: CrmProvider;
   crmId?: string;
   identities?: ProviderIdentity[];
+  provenance?: RecordProvenance;
   accountId?: string;
   ownerId?: string;
   name: string;