fullstackgtm 0.14.1 → 0.16.0

package/dist/resolve.js

@@ -0,0 +1,126 @@
+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 nameKey = normalizeName(c.name);
+    const open = snapshot.deals.filter((d) => d.isClosed !== true && d.isWon !== true);
+    if (c.accountId) {
+        const key = `${c.accountId}:${nameKey}`;
+        const matches = open
+            .filter((d) => `${d.accountId ?? "unlinked"}:${normalizeName(d.name)}` === key)
+            .map((d) => match(d.id, d.name, "deal_key", `open deal with the same name on account ${c.accountId}`));
+        if (matches.length > 0) {
+            return {
+                ...base,
+                verdict: "exists",
+                matches,
+                reason: `${matches.length} open deal(s) already match "${c.name}" on account ${c.accountId} — creating another would double-count pipeline. Update the existing deal.`,
+            };
+        }
+        const closedSameName = snapshot.deals.filter((d) => (d.isClosed === true || d.isWon === true) &&
+            d.accountId === c.accountId &&
+            normalizeName(d.name) === nameKey);
+        return {
+            ...base,
+            verdict: "safe_to_create",
+            matches: [],
+            reason: closedSameName.length > 0
+                ? `No open deal matches on account ${c.accountId}; ${closedSameName.length} closed deal(s) on it share the name (a re-open/renewal may be intended). Safe to create.`
+                : `No open deal matches "${c.name}" on account ${c.accountId}. Safe to create.`,
+        };
+    }
+    // No account scope: name-only matches across ALL open deals are ambiguous,
+    // never safe — a gate that ignores name collisions protects nobody.
+    const sameName = open
+        .filter((d) => normalizeName(d.name) === nameKey)
+        .map((d) => match(d.id, d.name, "name", `open deal with the same name on ${d.accountId ? `account ${d.accountId}` : "no account"}`));
+    if (sameName.length > 0) {
+        return {
+            ...base,
+            verdict: "ambiguous",
+            matches: sameName,
+            reason: `${sameName.length} open deal(s) named "${c.name}" exist (no --account-id supplied to scope the check). Confirm before creating — supply --account-id to resolve definitively.`,
+        };
+    }
+    return { ...base, verdict: "safe_to_create", matches: [], reason: `No open deal named "${c.name}" anywhere. Safe to create.` };
+}
+function contactName(row) {
+    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

@@ -9,7 +9,7 @@ export type CrmProvider = "salesforce" | "hubspot" | "mock" | "unknown" | (strin
 export type RiskLevel = "low" | "medium" | "high";
 export type ApprovalStatus = "draft" | "needs_approval" | "approved" | "rejected" | "applied";
 export type GtmObjectType = "account" | "contact" | "deal" | "user" | "activity";
-export type GtmEvidenceSourceSystem = "salesforce" | "hubspot" | "gong" | "chorus" | "fathom" | "manual" | "csv" | "mock" | "unknown";
+export type GtmEvidenceSourceSystem = "salesforce" | "hubspot" | "gong" | "chorus" | "fathom" | "manual" | "csv" | "mock" | "web" | "unknown";
 export type PatchOperationType = "set_field" | "clear_field" | "link_record" | "archive_record" | "create_task" | "merge_records";
 export type AuditFindingSeverity = "info" | "warning" | "critical";
 /**
@@ -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.16.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

@@ -39,6 +39,17 @@ import { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./
 import { builtinAuditRules } from "./rules.ts";
 import { sampleSnapshot } from "./sampleData.ts";
 import { normalizeTranscript, parseCall, suggestCallDeal, type ExtractedCallInsight, type ParsedCall } from "./calls.ts";
+import {
+  captureMarket,
+  computeFrontStates,
+  createFileObservationStore,
+  diffFrontStates,
+  loadMarketConfig,
+  starterMarketConfig,
+  validateObservationSet,
+  type ObservationSet,
+} from "./market.ts";
+import { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 import {
   DEFAULT_RUBRIC,
   detectProviderFromKey,
@@ -50,6 +61,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 +102,18 @@ 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 market init --category <name>   start a market map: vendors + claim taxonomy as reviewable config
+  fullstackgtm market capture [--config <path>] [--run <label>]
+  fullstackgtm market observe --from <observations.json>
+  fullstackgtm market fronts [--run <label>] [--diff <prior-run>] [--json]
+  fullstackgtm market report [--run <label>] [--format md|html] [--out <path>]
+                                               the live competitive map: capture vendor pages (content-addressed),
+                                               ingest intensity readings with verbatim-quote evidence, compute
+                                               deterministic front states (open/contested/owned/saturated) and
+                                               drift between runs, render the client-ready field report
   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 +821,157 @@ function buildCallPlan(
   };
 }
 
+/**
+ * The market map: claim taxonomy in a reviewable config file, page captures
+ * and append-only observations under the profile home, deterministic front
+ * states and reports computed from the store. Classification (LLM intensity
+ * readings) lands in a later change; until then `market observe --from`
+ * ingests proposal files produced by an agent or a human.
+ */
+async function marketCommand(args: string[]) {
+  const [subcommand, ...rest] = args;
+  const configPath = () => resolve(process.cwd(), option(rest, "--config") ?? "market.config.json");
+
+  if (!subcommand || subcommand === "--help") {
+    console.log(`Usage:
+market init --category <name> [--out <path>]   write a starter market.config.json
+market capture [--config <path>] [--run <label>]
+market observe --from <observations.json> [--config <path>]
+market fronts [--config <path>] [--run <label>] [--diff <prior-run>] [--json]
+market report [--config <path>] [--run <label>] [--format md|html] [--out <path>]
+
+The taxonomy (vendors + claims) is config you review and version; captures
+and observations live under ~/.fullstackgtm/market/<category> (profile-scoped,
+one client's category intel never bleeds into another's). Front states are
+recomputed deterministically on every invocation — never stored.`);
+    return;
+  }
+
+  if (subcommand === "init") {
+    const category = option(rest, "--category");
+    if (!category) throw new Error("market init requires --category <name>");
+    const outPath = resolve(process.cwd(), option(rest, "--out") ?? "market.config.json");
+    if (existsSync(outPath)) throw new Error(`${outPath} already exists — refusing to overwrite`);
+    writeFileSync(outPath, `${JSON.stringify(starterMarketConfig(category), null, 2)}\n`);
+    console.log(`Wrote ${outPath}. Fill in vendors and claims, then: fullstackgtm market capture`);
+    return;
+  }
+
+  const config = loadMarketConfig(configPath());
+  const store = createFileObservationStore(config.category);
+
+  if (subcommand === "capture") {
+    const result = await captureMarket(config, { runLabel: option(rest, "--run") ?? "run-1" });
+    for (const entry of result.entries) {
+      const flag = entry.captureHash && entry.textChars > 500 ? "" : "  <-- thin/empty";
+      console.log(
+        `${entry.vendorId.padEnd(16)} ${entry.kind.padEnd(8)} ${String(entry.httpStatus ?? "ERR").padEnd(4)} ${String(entry.textChars).padStart(7)} chars  ${entry.url}${flag}`,
+      );
+    }
+    console.log(`\nmanifest: ${result.manifestPath}`);
+    return;
+  }
+
+  if (subcommand === "observe") {
+    const fromPath = option(rest, "--from");
+    if (!fromPath) throw new Error("market observe requires --from <observations.json>");
+    const set = JSON.parse(readFileSync(resolve(process.cwd(), fromPath), "utf8")) as ObservationSet;
+    const problems = validateObservationSet(config, set);
+    if (problems.length > 0) {
+      console.error(`Rejected: ${problems.length} problem(s)`);
+      for (const problem of problems.slice(0, 20)) console.error(`  - ${problem}`);
+      process.exitCode = 1;
+      return;
+    }
+    await store.append(set);
+    console.log(`Appended ${set.runLabel}: ${set.observations.length} observations (${set.extractor})`);
+    return;
+  }
+
+  const loadSet = async (): Promise<ObservationSet> => {
+    const runLabel = option(rest, "--run");
+    const set = runLabel ? await store.get(runLabel) : await store.latest();
+    if (!set) {
+      throw new Error(
+        runLabel
+          ? `No observation run "${runLabel}" for ${config.category}`
+          : `No observations stored for ${config.category} — run market observe --from <file> first`,
+      );
+    }
+    return set;
+  };
+
+  if (subcommand === "fronts") {
+    const set = await loadSet();
+    const fronts = computeFrontStates(config, set);
+    const priorLabel = option(rest, "--diff");
+    const prior = priorLabel ? await store.get(priorLabel) : null;
+    if (priorLabel && !prior) throw new Error(`No observation run "${priorLabel}" to diff against`);
+    const drift = prior ? diffFrontStates(computeFrontStates(config, prior), fronts) : null;
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify({ runLabel: set.runLabel, fronts, drift }, null, 2));
+      return;
+    }
+    for (const front of fronts) {
+      const owner = front.state === "owned" ? ` → ${front.loudVendorIds[0]}` : "";
+      console.log(`${front.state.toUpperCase().padEnd(10)} ${front.claimId}${owner}`);
+    }
+    if (drift) {
+      console.log("");
+      if (drift.length === 0) console.log(`No front changes since ${priorLabel}.`);
+      for (const change of drift) console.log(`CHANGED   ${change.claimId}: ${change.before} → ${change.after}`);
+    }
+    return;
+  }
+
+  if (subcommand === "report") {
+    const set = await loadSet();
+    const format = option(rest, "--format") ?? "md";
+    const output = format === "html" ? marketMapToHtml(config, set) : marketMapToMarkdown(config, set);
+    const outPath = option(rest, "--out");
+    if (outPath) {
+      writeFileSync(resolve(process.cwd(), outPath), output);
+      console.log(`Wrote ${outPath}`);
+    } else {
+      console.log(output);
+    }
+    return;
+  }
+
+  throw new Error(`Unknown market subcommand: ${subcommand} (try: init, capture, observe, fronts, report)`);
+}
+
+/**
+ * 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 +1801,14 @@ export async function runCli(argv: string[]) {
     await callCommand(args);
     return;
   }
+  if (command === "resolve") {
+    await resolveCommand(args);
+    return;
+  }
+  if (command === "market") {
+    await marketCommand(args);
+    return;
+  }
   if (command === "profiles") {
     profilesCommand(args);
     return;