fullstackgtm 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.12.0] — 2026-06-11
+
+Governed merges: the Remediate layer of the
+[CRM-health lifecycle](./docs/crm-health-lifecycle.md). Duplicate detection
+now ends in an approvable merge, not a chore.
+
+### Added
+
+- **`merge_records` operation type**: merges a duplicate group
+  (`beforeValue` = group ids) into an approved survivor (`afterValue`).
+  HubSpot connector implements it via the v3 merge API for companies,
+  contacts, and deals — pairwise, survivor's values win, losers archived by
+  HubSpot, **irreversible** (called out in every operation's rollback text).
+  Refuses survivors outside the group; treats 404 losers as already merged,
+  so replayed plans are safe. Salesforce skips honestly (merge is SOAP/Apex
+  only on that platform).
+- **Survivor suggestions in `suggest`**: deterministic ranking — most
+  complete record, then most recent activity — with the evidence written
+  into the reason. **Capped at low confidence by design**: an irreversible
+  merge can never clear the default bulk-approval bar; accepting one takes
+  `--min-confidence low` or an explicit `--value`.
+
+### Changed
+
+- **The three duplicate rules now emit `merge_records`** (high risk,
+  approval required, irreversibility in the rollback text) instead of
+  `create_task` review chores — detection now connects to remediation
+  inside the governed loop.
+
 ## [0.11.1] — 2026-06-11
 
 Write-path integrity: fixes our own dupe faucets, found auditing the apply

package/README.md

@@ -59,7 +59,7 @@ fullstackgtm plans approve patch_plan_abc123 --values-from suggestions.json   #
 fullstackgtm apply --plan-id patch_plan_abc123 --provider hubspot
 ```
 
-Widen the bar deliberately: `--min-confidence low` accepts single-signal matches; `--include-creates` accepts `create:<Name>` values — approving one **creates the missing company/account record and links to it** in a single audited operation, so even record creation stays inside the typed, human-approved model. Conflicting or ambiguous evidence always yields *no* suggestion with an explanation, never a guess.
+Widen the bar deliberately: `--min-confidence low` accepts single-signal matches and **merge survivor suggestions** (irreversible merges are capped at low confidence by design, so the default bar never bulk-approves one); `--include-creates` accepts `create:<Name>` values — approving one **creates the missing company/account record and links to it** in a single audited operation, so even record creation stays inside the typed, human-approved model. Conflicting or ambiguous evidence always yields *no* suggestion with an explanation, never a guess.
 
 ```bash
 # 3. Hand the findings to whoever owns the CRM: a client-ready report

package/dist/connectors/hubspot.js

@@ -440,6 +440,74 @@ export function createHubspotConnector(options) {
             detail: `Archived ${objectPath}/${operation.objectId}.`,
         };
     }
+    /**
+     * Merge a duplicate group into the approved survivor via HubSpot's v3
+     * merge API (supported for contacts, companies, deals, and tickets).
+     * Merges are pairwise and IRREVERSIBLE; the survivor's values win on
+     * conflict and each loser is archived by HubSpot. A loser that is already
+     * gone (404 — e.g. a replayed plan) is treated as already merged.
+     */
+    async function mergeRecords(operation) {
+        const objectPath = OBJECT_PATHS[operation.objectType];
+        if (!objectPath || operation.objectType === "user" || operation.objectType === "activity") {
+            return {
+                operationId: operation.id,
+                status: "skipped",
+                detail: "merge_records is supported for accounts, contacts, and deals.",
+            };
+        }
+        const survivorId = String(operation.afterValue ?? "");
+        const groupIds = Array.isArray(operation.beforeValue)
+            ? operation.beforeValue.map((id) => String(id))
+            : [];
+        if (!survivorId || groupIds.length < 2) {
+            return {
+                operationId: operation.id,
+                status: "skipped",
+                detail: "merge_records needs a survivor id (afterValue) and the duplicate group ids (beforeValue).",
+            };
+        }
+        if (!groupIds.includes(survivorId)) {
+            return {
+                operationId: operation.id,
+                status: "skipped",
+                detail: `Survivor ${survivorId} is not in the duplicate group (${groupIds.join(", ")}); refusing to merge into an unrelated record.`,
+            };
+        }
+        const losers = groupIds.filter((id) => id !== survivorId);
+        const mergedIds = [];
+        const alreadyGoneIds = [];
+        for (const loser of losers) {
+            try {
+                await request(`/crm/v3/objects/${objectPath}/merge`, {
+                    method: "POST",
+                    body: JSON.stringify({ primaryObjectId: survivorId, objectIdToMerge: loser }),
+                });
+                mergedIds.push(loser);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (message.includes(" 404")) {
+                    alreadyGoneIds.push(loser); // replayed plan: loser already merged/archived
+                    continue;
+                }
+                return {
+                    operationId: operation.id,
+                    status: "failed",
+                    detail: `Merged ${mergedIds.length} of ${losers.length} into ${survivorId}, then failed on ${loser}: ${message}`,
+                    providerData: { survivorId, mergedIds, alreadyGoneIds },
+                };
+            }
+        }
+        return {
+            operationId: operation.id,
+            status: mergedIds.length === 0 && alreadyGoneIds.length === losers.length ? "skipped" : "applied",
+            detail: mergedIds.length === 0 && alreadyGoneIds.length === losers.length
+                ? `All ${losers.length} duplicates were already merged into ${survivorId}; nothing to do.`
+                : `Merged ${mergedIds.length} duplicate ${objectPath} into ${survivorId}${alreadyGoneIds.length ? ` (${alreadyGoneIds.length} already gone)` : ""}. Irreversible.`,
+            providerData: { survivorId, mergedIds, alreadyGoneIds },
+        };
+    }
     async function applyOperation(operation) {
         try {
             switch (operation.operation) {
@@ -450,6 +518,8 @@ export function createHubspotConnector(options) {
                     return await linkRecord(operation);
                 case "create_task":
                     return await createTask(operation);
+                case "merge_records":
+                    return await mergeRecords(operation);
                 case "archive_record":
                     return await archiveRecord(operation);
                 default:

package/dist/connectors/salesforce.js

@@ -338,6 +338,15 @@ export function createSalesforceConnector(options) {
                 }
                 case "create_task":
                     return await createTask(operation);
+                case "merge_records":
+                    // Salesforce merge exists only in the SOAP API and Apex (Lead,
+                    // Contact, Account, Case; max 3 records) — there is no REST merge
+                    // resource. Surface that honestly instead of half-merging.
+                    return {
+                        operationId: operation.id,
+                        status: "skipped",
+                        detail: "Salesforce merge requires the SOAP API or Apex (Lead/Contact/Account/Case only) — this REST connector cannot merge. Merge in the Salesforce UI, or archive the duplicates explicitly.",
+                    };
                 case "archive_record":
                     return await archiveRecord(operation);
                 default:

package/dist/rules.js

@@ -333,13 +333,14 @@ export const duplicateAccountDomainRule = {
                 id: patchOperationId("duplicate-account-domain", anchor.id),
                 objectType: "account",
                 objectId: anchor.id,
-                operation: "create_task",
-                field: "merge_review_task",
-                beforeValue: null,
-                afterValue: `Review ${accounts.length} accounts sharing ${domain} and merge duplicates`,
-                reason: "Duplicate accounts split pipeline, attribution, and ownership.",
-                riskLevel: "medium",
+                operation: "merge_records",
+                field: "merge",
+                beforeValue: accounts.map((account) => account.id),
+                afterValue: "requires_human_survivor_selection",
+                reason: `Duplicate accounts split pipeline, attribution, and ownership. Merge the ${accounts.length} accounts sharing ${domain} into one survivor.`,
+                riskLevel: "high",
                 approvalRequired: true,
+                rollback: "IRREVERSIBLE: provider merges cannot be unmerged. The pre-apply snapshot retains every record's field values; recreate a record manually from it if a merge was wrong.",
             });
         }
         return { findings, operations };
@@ -369,13 +370,14 @@ export const duplicateContactEmailRule = {
                 id: patchOperationId("duplicate-contact-email", anchor.id),
                 objectType: "contact",
                 objectId: anchor.id,
-                operation: "create_task",
-                field: "merge_review_task",
-                beforeValue: null,
-                afterValue: `Review ${contacts.length} contacts sharing ${email} and merge duplicates`,
-                reason: "Duplicate contacts fragment engagement history and double-route outreach.",
-                riskLevel: "low",
+                operation: "merge_records",
+                field: "merge",
+                beforeValue: contacts.map((contact) => contact.id),
+                afterValue: "requires_human_survivor_selection",
+                reason: `Duplicate contacts fragment engagement history and double-route outreach. Merge the ${contacts.length} contacts sharing ${email} into one survivor.`,
+                riskLevel: "high",
                 approvalRequired: true,
+                rollback: "IRREVERSIBLE: provider merges cannot be unmerged. The pre-apply snapshot retains every record's field values; recreate a record manually from it if a merge was wrong.",
             });
         }
         return { findings, operations };
@@ -415,13 +417,14 @@ export const duplicateOpenDealRule = {
                 id: patchOperationId("duplicate-open-deal", anchor.id),
                 objectType: "deal",
                 objectId: anchor.id,
-                operation: "create_task",
-                field: "merge_review_task",
-                beforeValue: null,
-                afterValue: `Review ${deals.length} duplicate open deals named "${anchor.name}" — keep one, archive ${deals.length - 1}`,
-                reason: "Duplicate open deals inflate pipeline and forecast the same revenue more than once.",
-                riskLevel: "medium",
+                operation: "merge_records",
+                field: "merge",
+                beforeValue: deals.map((deal) => deal.id),
+                afterValue: "requires_human_survivor_selection",
+                reason: `Duplicate open deals inflate pipeline and forecast the same revenue more than once. Merge the ${deals.length} deals named "${anchor.name}" into one survivor.`,
+                riskLevel: "high",
                 approvalRequired: true,
+                rollback: "IRREVERSIBLE: provider merges cannot be unmerged. The pre-apply snapshot retains every record's field values; recreate a record manually from it if a merge was wrong.",
             });
         }
         return { findings, operations };

package/dist/suggest.js

@@ -22,6 +22,10 @@ export function suggestValues(plan, snapshot) {
             suggestions.push(suggestDealAccount(operation, dealsById, accountsByNorm, accountsById, contactsByName));
             continue;
         }
+        if (placeholder === "requires_human_survivor_selection") {
+            suggestions.push(suggestSurvivor(operation, snapshot, dealsById));
+            continue;
+        }
         if (placeholder === "requires_human_owner_selection" && activeUsers.length === 1) {
             suggestions.push({
                 operationId: operation.id,
@@ -140,6 +144,79 @@ function suggestDealAccount(operation, dealsById, accountsByNorm, accountsById,
             : `Deal name "${deal.name}" has no "Contact - Company" pattern to derive a company from. Supply --value ${operation.id}=<accountId> or create:<Company Name>.`,
     };
 }
+/**
+ * Survivor selection for merge_records. Ranking is deterministic and
+ * evidence-based: most complete record first (count of populated canonical
+ * fields), most recent activity as the tiebreaker, group order last.
+ * Confidence is capped at "low" by design: merges are irreversible, so a
+ * survivor suggestion must never clear the default bulk-approval bar —
+ * accepting one requires --min-confidence low or an explicit --value.
+ */
+function suggestSurvivor(operation, snapshot, dealsById) {
+    const base = {
+        operationId: operation.id,
+        objectType: operation.objectType,
+        objectId: operation.objectId,
+        objectName: dealsById.get(operation.objectId)?.name,
+        placeholder: "requires_human_survivor_selection",
+    };
+    const groupIds = Array.isArray(operation.beforeValue)
+        ? operation.beforeValue.map((id) => String(id))
+        : [];
+    if (groupIds.length < 2) {
+        return {
+            ...base,
+            suggestedValue: null,
+            confidence: "none",
+            reason: "Operation does not carry a duplicate group (expected ids in beforeValue).",
+        };
+    }
+    const collection = operation.objectType === "account"
+        ? snapshot.accounts
+        : operation.objectType === "contact"
+            ? snapshot.contacts
+            : operation.objectType === "deal"
+                ? snapshot.deals
+                : [];
+    const records = groupIds
+        .map((id) => collection.find((row) => row.id === id))
+        .filter((row) => row !== undefined);
+    if (records.length !== groupIds.length) {
+        return {
+            ...base,
+            suggestedValue: null,
+            confidence: "none",
+            reason: "Not every group member is present in the snapshot; re-run the audit before merging.",
+        };
+    }
+    const ranked = [...records].sort((a, b) => {
+        const completeness = populatedFields(b) - populatedFields(a);
+        if (completeness !== 0)
+            return completeness;
+        return activityMs(b) - activityMs(a);
+    });
+    const winner = ranked[0];
+    const runnerUp = ranked[1];
+    const name = "name" in winner && typeof winner.name === "string" ? winner.name : winner.id;
+    return {
+        ...base,
+        suggestedValue: winner.id,
+        confidence: "low",
+        reason: `"${name}" (${winner.id}) is the most complete record in the group ` +
+            `(${populatedFields(winner)} populated fields vs ${populatedFields(runnerUp)}` +
+            `${activityMs(winner) > activityMs(runnerUp) ? ", and more recent activity" : ""}). ` +
+            `Merging is IRREVERSIBLE — survivor suggestions never exceed low confidence; ` +
+            `approve with --min-confidence low or an explicit --value after review.`,
+    };
+}
+function populatedFields(record) {
+    return Object.values(record).filter((value) => value !== undefined && value !== null && value !== "").length;
+}
+function activityMs(record) {
+    const value = record.lastActivityAt;
+    const parsed = value ? Date.parse(value) : NaN;
+    return Number.isFinite(parsed) ? parsed : 0;
+}
 function normalize(value) {
     return value
         .toLowerCase()

package/dist/types.d.ts

@@ -10,7 +10,7 @@ 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 PatchOperationType = "set_field" | "clear_field" | "link_record" | "archive_record" | "create_task";
+export type PatchOperationType = "set_field" | "clear_field" | "link_record" | "archive_record" | "create_task" | "merge_records";
 export type AuditFindingSeverity = "info" | "warning" | "critical";
 /**
  * One claim that a canonical record exists in an external system. A record

package/docs/api.md

@@ -40,7 +40,7 @@ release.
 - `GtmConnector` — `{ provider, fetchSnapshot(), applyOperation?, readField?, fetchChanges? }`.
   - Connectors never silently drop unresolvable records; audits surface them.
   - `fetchChanges(sinceIso)` returns a partial snapshot; change feeds may omit associations.
-- `createHubspotConnector(options)` — read/write/readField/fetchChanges. `applyOperation` implements every `PatchOperationType`: `set_field`, `clear_field`, `link_record`, `create_task`, `archive_record`.
+- `createHubspotConnector(options)` — read/write/readField/fetchChanges. `applyOperation` implements every `PatchOperationType`: `set_field`, `clear_field`, `link_record`, `create_task`, `archive_record`, `merge_records` (HubSpot v3 merge — pairwise, irreversible; survivor must belong to the duplicate group). The Salesforce connector skips `merge_records` honestly (SOAP/Apex-only on that platform).
 - `createSalesforceConnector(options)` — read/write/readField/fetchChanges; probabilities normalized to 0..1; `applyOperation` implements every operation type.
 - `createStripeConnector(options)` — read-only billing by design (`applyOperation` returns `skipped`); email domains are the cross-system merge keys. Implements `fetchChanges` (incremental via `created[gte]`).
 

package/docs/crm-health-lifecycle.md

@@ -130,6 +130,6 @@ Lessons from auditing our own apply path:
 | Release | Scope |
 | --- | --- |
 | 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 | `merge_records` (HubSpot contacts/companies/deals) + survivor suggestions; rules emit governed merges for dupe groups |
+| 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 |
 | docs | The nightly watch recipe (existing flags, documented as CRM CI) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.11.1",
+  "version": "0.12.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/connectors/hubspot.ts

@@ -542,6 +542,75 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     };
   }
 
+  /**
+   * Merge a duplicate group into the approved survivor via HubSpot's v3
+   * merge API (supported for contacts, companies, deals, and tickets).
+   * Merges are pairwise and IRREVERSIBLE; the survivor's values win on
+   * conflict and each loser is archived by HubSpot. A loser that is already
+   * gone (404 — e.g. a replayed plan) is treated as already merged.
+   */
+  async function mergeRecords(operation: PatchOperation): Promise<PatchOperationResult> {
+    const objectPath = OBJECT_PATHS[operation.objectType];
+    if (!objectPath || operation.objectType === "user" || operation.objectType === "activity") {
+      return {
+        operationId: operation.id,
+        status: "skipped",
+        detail: "merge_records is supported for accounts, contacts, and deals.",
+      };
+    }
+    const survivorId = String(operation.afterValue ?? "");
+    const groupIds = Array.isArray(operation.beforeValue)
+      ? operation.beforeValue.map((id) => String(id))
+      : [];
+    if (!survivorId || groupIds.length < 2) {
+      return {
+        operationId: operation.id,
+        status: "skipped",
+        detail: "merge_records needs a survivor id (afterValue) and the duplicate group ids (beforeValue).",
+      };
+    }
+    if (!groupIds.includes(survivorId)) {
+      return {
+        operationId: operation.id,
+        status: "skipped",
+        detail: `Survivor ${survivorId} is not in the duplicate group (${groupIds.join(", ")}); refusing to merge into an unrelated record.`,
+      };
+    }
+    const losers = groupIds.filter((id) => id !== survivorId);
+    const mergedIds: string[] = [];
+    const alreadyGoneIds: string[] = [];
+    for (const loser of losers) {
+      try {
+        await request(`/crm/v3/objects/${objectPath}/merge`, {
+          method: "POST",
+          body: JSON.stringify({ primaryObjectId: survivorId, objectIdToMerge: loser }),
+        });
+        mergedIds.push(loser);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes(" 404")) {
+          alreadyGoneIds.push(loser); // replayed plan: loser already merged/archived
+          continue;
+        }
+        return {
+          operationId: operation.id,
+          status: "failed",
+          detail: `Merged ${mergedIds.length} of ${losers.length} into ${survivorId}, then failed on ${loser}: ${message}`,
+          providerData: { survivorId, mergedIds, alreadyGoneIds },
+        };
+      }
+    }
+    return {
+      operationId: operation.id,
+      status: mergedIds.length === 0 && alreadyGoneIds.length === losers.length ? "skipped" : "applied",
+      detail:
+        mergedIds.length === 0 && alreadyGoneIds.length === losers.length
+          ? `All ${losers.length} duplicates were already merged into ${survivorId}; nothing to do.`
+          : `Merged ${mergedIds.length} duplicate ${objectPath} into ${survivorId}${alreadyGoneIds.length ? ` (${alreadyGoneIds.length} already gone)` : ""}. Irreversible.`,
+      providerData: { survivorId, mergedIds, alreadyGoneIds },
+    };
+  }
+
   async function applyOperation(operation: PatchOperation): Promise<PatchOperationResult> {
     try {
       switch (operation.operation) {
@@ -552,6 +621,8 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
           return await linkRecord(operation);
         case "create_task":
           return await createTask(operation);
+        case "merge_records":
+          return await mergeRecords(operation);
         case "archive_record":
           return await archiveRecord(operation);
         default:

package/src/connectors/salesforce.ts

@@ -435,6 +435,16 @@ export function createSalesforceConnector(
         }
         case "create_task":
           return await createTask(operation);
+        case "merge_records":
+          // Salesforce merge exists only in the SOAP API and Apex (Lead,
+          // Contact, Account, Case; max 3 records) — there is no REST merge
+          // resource. Surface that honestly instead of half-merging.
+          return {
+            operationId: operation.id,
+            status: "skipped",
+            detail:
+              "Salesforce merge requires the SOAP API or Apex (Lead/Contact/Account/Case only) — this REST connector cannot merge. Merge in the Salesforce UI, or archive the duplicates explicitly.",
+          };
         case "archive_record":
           return await archiveRecord(operation);
         default:

package/src/rules.ts

@@ -350,13 +350,15 @@ export const duplicateAccountDomainRule: GtmAuditRule = {
         id: patchOperationId("duplicate-account-domain", anchor.id),
         objectType: "account" as const,
         objectId: anchor.id,
-        operation: "create_task" as const,
-        field: "merge_review_task",
-        beforeValue: null,
-        afterValue: `Review ${accounts.length} accounts sharing ${domain} and merge duplicates`,
-        reason: "Duplicate accounts split pipeline, attribution, and ownership.",
-        riskLevel: "medium" as const,
+        operation: "merge_records" as const,
+        field: "merge",
+        beforeValue: accounts.map((account) => account.id),
+        afterValue: "requires_human_survivor_selection",
+        reason: `Duplicate accounts split pipeline, attribution, and ownership. Merge the ${accounts.length} accounts sharing ${domain} into one survivor.`,
+        riskLevel: "high" as const,
         approvalRequired: true,
+        rollback:
+          "IRREVERSIBLE: provider merges cannot be unmerged. The pre-apply snapshot retains every record's field values; recreate a record manually from it if a merge was wrong.",
       });
     }
     return { findings, operations };
@@ -388,13 +390,15 @@ export const duplicateContactEmailRule: GtmAuditRule = {
         id: patchOperationId("duplicate-contact-email", anchor.id),
         objectType: "contact" as const,
         objectId: anchor.id,
-        operation: "create_task" as const,
-        field: "merge_review_task",
-        beforeValue: null,
-        afterValue: `Review ${contacts.length} contacts sharing ${email} and merge duplicates`,
-        reason: "Duplicate contacts fragment engagement history and double-route outreach.",
-        riskLevel: "low" as const,
+        operation: "merge_records" as const,
+        field: "merge",
+        beforeValue: contacts.map((contact) => contact.id),
+        afterValue: "requires_human_survivor_selection",
+        reason: `Duplicate contacts fragment engagement history and double-route outreach. Merge the ${contacts.length} contacts sharing ${email} into one survivor.`,
+        riskLevel: "high" as const,
         approvalRequired: true,
+        rollback:
+          "IRREVERSIBLE: provider merges cannot be unmerged. The pre-apply snapshot retains every record's field values; recreate a record manually from it if a merge was wrong.",
       });
     }
     return { findings, operations };
@@ -437,13 +441,15 @@ export const duplicateOpenDealRule: GtmAuditRule = {
         id: patchOperationId("duplicate-open-deal", anchor.id),
         objectType: "deal" as const,
         objectId: anchor.id,
-        operation: "create_task" as const,
-        field: "merge_review_task",
-        beforeValue: null,
-        afterValue: `Review ${deals.length} duplicate open deals named "${anchor.name}" — keep one, archive ${deals.length - 1}`,
-        reason: "Duplicate open deals inflate pipeline and forecast the same revenue more than once.",
-        riskLevel: "medium" as const,
+        operation: "merge_records" as const,
+        field: "merge",
+        beforeValue: deals.map((deal) => deal.id),
+        afterValue: "requires_human_survivor_selection",
+        reason: `Duplicate open deals inflate pipeline and forecast the same revenue more than once. Merge the ${deals.length} deals named "${anchor.name}" into one survivor.`,
+        riskLevel: "high" as const,
         approvalRequired: true,
+        rollback:
+          "IRREVERSIBLE: provider merges cannot be unmerged. The pre-apply snapshot retains every record's field values; recreate a record manually from it if a merge was wrong.",
       });
     }
     return { findings, operations };

package/src/suggest.ts

@@ -62,6 +62,11 @@ export function suggestValues(
       continue;
     }
 
+    if (placeholder === "requires_human_survivor_selection") {
+      suggestions.push(suggestSurvivor(operation, snapshot, dealsById));
+      continue;
+    }
+
     if (placeholder === "requires_human_owner_selection" && activeUsers.length === 1) {
       suggestions.push({
         operationId: operation.id,
@@ -194,6 +199,89 @@ function suggestDealAccount(
   };
 }
 
+/**
+ * Survivor selection for merge_records. Ranking is deterministic and
+ * evidence-based: most complete record first (count of populated canonical
+ * fields), most recent activity as the tiebreaker, group order last.
+ * Confidence is capped at "low" by design: merges are irreversible, so a
+ * survivor suggestion must never clear the default bulk-approval bar —
+ * accepting one requires --min-confidence low or an explicit --value.
+ */
+function suggestSurvivor(
+  operation: PatchOperation,
+  snapshot: CanonicalGtmSnapshot,
+  dealsById: Map<string, { name: string }>,
+): ValueSuggestion {
+  const base = {
+    operationId: operation.id,
+    objectType: operation.objectType,
+    objectId: operation.objectId,
+    objectName: dealsById.get(operation.objectId)?.name,
+    placeholder: "requires_human_survivor_selection",
+  };
+  const groupIds = Array.isArray(operation.beforeValue)
+    ? operation.beforeValue.map((id) => String(id))
+    : [];
+  if (groupIds.length < 2) {
+    return {
+      ...base,
+      suggestedValue: null,
+      confidence: "none",
+      reason: "Operation does not carry a duplicate group (expected ids in beforeValue).",
+    };
+  }
+  const collection =
+    operation.objectType === "account"
+      ? snapshot.accounts
+      : operation.objectType === "contact"
+        ? snapshot.contacts
+        : operation.objectType === "deal"
+          ? snapshot.deals
+          : [];
+  const records = groupIds
+    .map((id) => collection.find((row) => row.id === id))
+    .filter((row): row is NonNullable<typeof row> => row !== undefined);
+  if (records.length !== groupIds.length) {
+    return {
+      ...base,
+      suggestedValue: null,
+      confidence: "none",
+      reason: "Not every group member is present in the snapshot; re-run the audit before merging.",
+    };
+  }
+  const ranked = [...records].sort((a, b) => {
+    const completeness = populatedFields(b) - populatedFields(a);
+    if (completeness !== 0) return completeness;
+    return activityMs(b) - activityMs(a);
+  });
+  const winner = ranked[0];
+  const runnerUp = ranked[1];
+  const name = "name" in winner && typeof winner.name === "string" ? winner.name : winner.id;
+  return {
+    ...base,
+    suggestedValue: winner.id,
+    confidence: "low",
+    reason:
+      `"${name}" (${winner.id}) is the most complete record in the group ` +
+      `(${populatedFields(winner)} populated fields vs ${populatedFields(runnerUp)}` +
+      `${activityMs(winner) > activityMs(runnerUp) ? ", and more recent activity" : ""}). ` +
+      `Merging is IRREVERSIBLE — survivor suggestions never exceed low confidence; ` +
+      `approve with --min-confidence low or an explicit --value after review.`,
+  };
+}
+
+function populatedFields(record: object) {
+  return Object.values(record).filter(
+    (value) => value !== undefined && value !== null && value !== "",
+  ).length;
+}
+
+function activityMs(record: object) {
+  const value = (record as { lastActivityAt?: string }).lastActivityAt;
+  const parsed = value ? Date.parse(value) : NaN;
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
 function normalize(value: string) {
   return value
     .toLowerCase()

package/src/types.ts

@@ -41,7 +41,11 @@ export type PatchOperationType =
   | "clear_field"
   | "link_record"
   | "archive_record"
-  | "create_task";
+  | "create_task"
+  // Merge a duplicate group into a survivor. beforeValue is the group's
+  // record ids; afterValue is the survivor id (requires_human_survivor_selection
+  // until a human picks). IRREVERSIBLE on every provider that supports it.
+  | "merge_records";
 
 export type AuditFindingSeverity = "info" | "warning" | "critical";