fullstackgtm 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -5,6 +5,48 @@ 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).
+
+### Fixed
+
+- **`call score` no longer suggests a flag it rejects**: the keyless error
+  said "pass --deterministic" but score has no non-LLM mode — its error now
+  says exactly that. Rubric files are also validated *before* the
+  credential check (keyless users see rubric errors), and a non-JSON rubric
+  names the file and the expected shape instead of a raw parse error.
+- **NDJSON rows carry `extractor`** — LLM and deterministic rows were
+  per-row indistinguishable in warehouse loads, contradicting the
+  provenance claim. (Docs wording was right at the parse-result and
+  evidence level; now it is true per-row too.)
+- **`call … --help` prints help** instead of being shadowed by argument
+  and credential checks.
+- `login anthropic|openai` gets the same explicit argv-secret rejection
+  (`--token`/`--key`/`--api-key`) as the CRM providers.
+
 ## [0.14.0] — 2026-06-11
 
 LLM-powered call intelligence, bring-your-own-key. The dry-run replications

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
@@ -418,6 +422,17 @@ function parseValueOverrides(args) {
 }
 async function callCommand(args) {
     const [subcommand, ...rest] = args;
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(`call parse --transcript <file> [--title t] [--source s] [--model m] [--deterministic] [--json|--ndjson] [--out <path>]
+call score --transcript <file>|--call <parsed.json> [--rubric <rubric.json>] [--model m] [--json|--out <path>]
+call link --attendees <a@x.com,...> | --domain <x.com>  [source options] [--json]
+call plan --transcript <file>|--call <parsed.json> --deal <id> [source options] [--save|--json]
+
+parse/score default to LLM extraction (Anthropic or OpenAI key via env,
+\`login anthropic|openai\`, or a one-time prompt). parse --deterministic is
+the free keyword baseline; score always needs a key (scoring is LLM work).`);
+        return;
+    }
     const loadParsedCall = async () => {
         const callPath = option(rest, "--call");
         if (callPath) {
@@ -462,6 +477,7 @@ async function callCommand(args) {
                     call_id: parsed.id,
                     call_title: parsed.title ?? null,
                     source_system: parsed.sourceSystem,
+                    extractor: parsed.extractor,
                     type: insight.type,
                     title: insight.title,
                     text: insight.text,
@@ -534,11 +550,19 @@ async function callCommand(args) {
         return;
     }
     if (subcommand === "score") {
-        const credential = await requireLlmCredential();
+        // Rubric problems surface before any credential or API work.
         const rubricPath = option(rest, "--rubric");
-        const rubric = rubricPath
-            ? parseRubric(readFileSync(resolve(process.cwd(), rubricPath), "utf8"))
-            : DEFAULT_RUBRIC;
+        let rubric = DEFAULT_RUBRIC;
+        if (rubricPath) {
+            const rubricRaw = readFileSync(resolve(process.cwd(), rubricPath), "utf8");
+            try {
+                rubric = parseRubric(rubricRaw);
+            }
+            catch (error) {
+                throw new Error(`${rubricPath} is not a valid rubric: ${error instanceof Error ? error.message : String(error)} Expected JSON like { "scale": 5, "dimensions": [{ "name": "...", "weight": 1, "rubric": "..." }] }.`);
+            }
+        }
+        const credential = await requireLlmCredential("score");
         const transcriptPath = option(rest, "--transcript");
         let transcriptText;
         let title = option(rest, "--title") ?? undefined;
@@ -577,12 +601,14 @@ async function callCommand(args) {
  * TTY a missing key is captured once (validated, stored 0600 like provider
  * logins). Non-interactive contexts get an actionable error instead.
  */
-async function requireLlmCredential() {
+async function requireLlmCredential(command = "parse") {
     const resolved = resolveLlmCredential();
     if (resolved)
         return resolved;
+    // Scoring is inherently LLM work — there is no keyword fallback to suggest.
+    const fallbackHint = command === "parse" ? ", or pass --deterministic for the free keyword baseline" : " (call score has no non-LLM mode)";
     if (!process.stdin.isTTY) {
-        throw new Error("LLM extraction needs an API key. Set ANTHROPIC_API_KEY or OPENAI_API_KEY, run `echo \"$KEY\" | fullstackgtm login anthropic` (or `login openai`) once, or pass --deterministic for the free keyword baseline.");
+        throw new Error(`LLM ${command === "score" ? "scoring" : "extraction"} needs an API key. Set ANTHROPIC_API_KEY or OPENAI_API_KEY, or run \`echo "$KEY" | fullstackgtm login anthropic\` (or \`login openai\`) once${fallbackHint}.`);
     }
     console.error("LLM parsing needs an API key (Anthropic or OpenAI) — yours, used directly with the provider.");
     console.error(`Paste it once; it is validated and stored at ${credentialsPath()} (file mode 0600), like CRM logins.`);
@@ -689,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");
@@ -1177,6 +1235,7 @@ async function login(args) {
         return;
     }
     if (provider === "anthropic" || provider === "openai") {
+        rejectArgvSecret(args, "--token", "--key", "--api-key");
         const key = await readSecret(`${provider} API key (${provider === "anthropic" ? "sk-ant-..." : "sk-..."})`);
         if (!key)
             throw new Error(`No ${provider} key provided.`);
@@ -1433,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({