fullstackgtm 0.47.0 → 0.48.0

package/dist/rules.js

@@ -36,6 +36,91 @@ export function auditFindingId(ruleId, objectId) {
 export function patchOperationId(ruleId, objectId) {
     return `op_${stableHash(`${ruleId}:${objectId}`)}`;
 }
+const OPEN_DEAL_FLAGS_ASSUMPTION = {
+    id: "open-deal-derived-from-closed-won-flags",
+    text: "Derived open-deal status from canonical isClosed/isWon flags; a deal is open when neither flag is true.",
+    source: "CanonicalDeal.isClosed/isWon",
+    confidence: "derived",
+};
+const MISSING_CLOSED_WON_FLAGS_ASSUMPTION = {
+    id: "missing-closed-won-flags-treated-open",
+    text: "Treated deals with missing isClosed/isWon flags as open so hygiene rules do not silently ignore active pipeline.",
+    source: "CanonicalDeal.isClosed/isWon",
+    confidence: "heuristic",
+};
+const ORPHAN_ACCOUNT_RELATIONSHIP_ASSUMPTION = {
+    id: "account-without-contacts-or-deals-treated-orphan",
+    text: "Treated an account as orphaned when the snapshot has no contacts and no deals linked to that account.",
+    source: "snapshot account/contact/deal associations",
+    confidence: "derived",
+};
+const DEAL_OWNER_POLICY_ASSUMPTION = {
+    id: "deal-owner-required-by-policy",
+    text: "Treated a missing or unknown deal owner as invalid when requireDealOwner policy is enabled.",
+    source: "GtmPolicy.requireDealOwner",
+    confidence: "heuristic",
+};
+const DEAL_ACCOUNT_POLICY_ASSUMPTION = {
+    id: "deal-account-required-by-policy",
+    text: "Treated a missing or unknown deal account link as invalid when requireAccountForDeal policy is enabled.",
+    source: "GtmPolicy.requireAccountForDeal",
+    confidence: "heuristic",
+};
+const DEAL_AMOUNT_POLICY_ASSUMPTION = {
+    id: "open-deal-amount-required-by-policy",
+    text: "Treated open deals with missing or zero amount as forecast-risk findings unless requireDealAmount is disabled.",
+    source: "GtmPolicy.requireDealAmount",
+    confidence: "heuristic",
+};
+const DUPLICATE_ACCOUNT_DOMAIN_ASSUMPTION = {
+    id: "same-normalized-domain-duplicate-account",
+    text: "Treated accounts with the same normalized domain as duplicate-account candidates.",
+    source: "CanonicalAccount.domain",
+    confidence: "heuristic",
+};
+const DUPLICATE_CONTACT_EMAIL_ASSUMPTION = {
+    id: "same-email-duplicate-contact",
+    text: "Treated contacts with the same lowercased email address as duplicate-contact candidates.",
+    source: "CanonicalContact.email",
+    confidence: "heuristic",
+};
+const DUPLICATE_OPEN_DEAL_ASSUMPTION = {
+    id: "same-account-and-name-duplicate-open-deal",
+    text: "Treated open deals with the same normalized name on the same account scope as duplicate-opportunity candidates.",
+    source: "CanonicalDeal.accountId/name",
+    confidence: "heuristic",
+};
+const ACCOUNT_WITH_OPEN_DEAL_NEEDS_CONTACT_ASSUMPTION = {
+    id: "open-pipeline-account-needs-contact",
+    text: "Treated accounts with open pipeline but no linked contacts as coverage gaps requiring a buying-committee contact.",
+    source: "snapshot account/contact/deal associations",
+    confidence: "heuristic",
+};
+const SINGLE_SOURCE_ACCOUNT_ASSUMPTION = {
+    id: "single-source-account-is-cross-system-gap",
+    text: "Treated an account present in only one connected system as a cross-system reconciliation gap.",
+    source: "ProviderIdentity.provider",
+    confidence: "heuristic",
+};
+function staleDealPolicyAssumption(days) {
+    return {
+        id: "stale-deal-days-policy",
+        text: `Treated open deals with no recorded activity for more than ${days} days as stale.`,
+        source: "GtmPolicy.staleDealDays",
+        confidence: "heuristic",
+    };
+}
+function closingSoonPolicyAssumption(windowDays, idleDays) {
+    return {
+        id: "closing-soon-idle-policy",
+        text: `Treated open deals closing within ${windowDays} days and idle for more than ${idleDays} days as silent slip risk.`,
+        source: "GtmPolicy.closingSoonDays/closingSoonIdleDays",
+        confidence: "heuristic",
+    };
+}
+function assumptionsIfFindings(findings, assumptions) {
+    return findings.length > 0 ? assumptions : undefined;
+}
 export function stableHash(value) {
     let hash = 0;
     for (let index = 0; index < value.length; index += 1) {
@@ -150,7 +235,11 @@ export const orphanAccountRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [ORPHAN_ACCOUNT_RELATIONSHIP_ASSUMPTION]),
+        };
     },
 };
 export const missingDealOwnerRule = {
@@ -180,7 +269,11 @@ export const missingDealOwnerRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [DEAL_OWNER_POLICY_ASSUMPTION]),
+        };
     },
 };
 export const missingDealAccountRule = {
@@ -210,7 +303,11 @@ export const missingDealAccountRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [DEAL_ACCOUNT_POLICY_ASSUMPTION]),
+        };
     },
 };
 export const pastCloseDateRule = {
@@ -240,7 +337,14 @@ export const pastCloseDateRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [
+                OPEN_DEAL_FLAGS_ASSUMPTION,
+                MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+            ]),
+        };
     },
 };
 export const staleDealRule = {
@@ -280,7 +384,15 @@ export const staleDealRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [
+                OPEN_DEAL_FLAGS_ASSUMPTION,
+                MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+                staleDealPolicyAssumption(policy.staleDealDays),
+            ]),
+        };
     },
 };
 export const missingDealAmountRule = {
@@ -312,7 +424,15 @@ export const missingDealAmountRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [
+                OPEN_DEAL_FLAGS_ASSUMPTION,
+                MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+                DEAL_AMOUNT_POLICY_ASSUMPTION,
+            ]),
+        };
     },
 };
 function duplicateGroups(items, keyOf) {
@@ -365,7 +485,11 @@ export const duplicateAccountDomainRule = {
                 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 };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [DUPLICATE_ACCOUNT_DOMAIN_ASSUMPTION]),
+        };
     },
 };
 export const duplicateContactEmailRule = {
@@ -402,7 +526,11 @@ export const duplicateContactEmailRule = {
                 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 };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [DUPLICATE_CONTACT_EMAIL_ASSUMPTION]),
+        };
     },
 };
 export const duplicateOpenDealRule = {
@@ -449,7 +577,15 @@ export const duplicateOpenDealRule = {
                 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 };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [
+                OPEN_DEAL_FLAGS_ASSUMPTION,
+                MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+                DUPLICATE_OPEN_DEAL_ASSUMPTION,
+            ]),
+        };
     },
 };
 export const activeDealAccountWithoutContactsRule = {
@@ -491,7 +627,15 @@ export const activeDealAccountWithoutContactsRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [
+                OPEN_DEAL_FLAGS_ASSUMPTION,
+                MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+                ACCOUNT_WITH_OPEN_DEAL_NEEDS_CONTACT_ASSUMPTION,
+            ]),
+        };
     },
 };
 export const closingSoonInactiveRule = {
@@ -536,12 +680,21 @@ export const closingSoonInactiveRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [
+                OPEN_DEAL_FLAGS_ASSUMPTION,
+                MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+                closingSoonPolicyAssumption(windowDays, idleDays),
+            ]),
+        };
     },
 };
 export const accountSingleSourceRule = {
     id: "account-single-source",
     title: "Account exists in only one connected system",
+    emitsOperations: false,
     description: "On merged multi-system snapshots, flags accounts known to just one source — the seams where GTM systems disagree.",
     category: "cross-system",
     evaluate: ({ snapshot }) => {
@@ -566,9 +719,16 @@ export const accountSingleSourceRule = {
                 recommendation: "Check whether the account is missing from the other systems or matched under a different domain/name.",
             });
         }
-        return { findings, operations: [] };
+        return {
+            findings,
+            operations: [],
+            assumptions: assumptionsIfFindings(findings, [SINGLE_SOURCE_ACCOUNT_ASSUMPTION]),
+        };
     },
 };
+export function isFindingsOnlyRule(rule) {
+    return rule.emitsOperations === false;
+}
 export const builtinAuditRules = [
     orphanAccountRule,
     missingDealOwnerRule,

package/dist/types.d.ts

@@ -58,6 +58,13 @@ export type CreateRecordPayload = {
     dealPipeline?: string;
 };
 export type AuditFindingSeverity = "info" | "warning" | "critical";
+export type PatchPlanAssumptionConfidence = "derived" | "heuristic" | "guess";
+export type PatchPlanAssumption = {
+    id: string;
+    text: string;
+    source?: string;
+    confidence?: PatchPlanAssumptionConfidence;
+};
 /**
  * One claim that a canonical record exists in an external system. A record
  * merged from several providers carries one identity per provider.
@@ -323,6 +330,10 @@ export type PatchPlan = {
      *  Account/contact hygiene findings are NOT here; read `findings` for those. */
     pipelineFindings?: PipelineFinding[];
     evidence?: GtmEvidence[];
+    /** Assumptions used to turn audit observations into findings and operations. */
+    assumptions?: PatchPlanAssumption[];
+    /** Human decisions or unresolved questions that affect how the plan should be applied. */
+    openQuestions?: string[];
     operations: PatchOperation[];
     /**
      * The filter this plan's operations were selected by. Re-evaluated per
@@ -374,6 +385,8 @@ export type GtmRuleContext = {
 export type GtmRuleResult = {
     findings: AuditFinding[];
     operations: PatchOperation[];
+    /** Rule-level assumptions that explain the policy or heuristic behind returned findings. */
+    assumptions?: PatchPlanAssumption[];
 };
 /**
  * A deterministic audit rule. Rules read the snapshot through the context and
@@ -385,6 +398,8 @@ export type GtmAuditRule = {
     description: string;
     /** Grouping for docs and discovery, e.g. "hygiene", "forecast", "coverage". */
     category?: string;
+    /** False for findings-only rules whose evaluator intentionally emits no patch operations. */
+    emitsOperations?: boolean;
     evaluate: (context: GtmRuleContext) => GtmRuleResult;
 };
 export type PatchOperationResult = {

package/docs/api.md

@@ -69,7 +69,8 @@ release.
 Commands: `init`, `login` / `logout`, `snapshot`, `audit`, `report`, `diff`, `merge`, `plans`,
 `apply`, `suggest`, `audit-log` (`export` / `verify`),
 `call` (`parse` / `classify` / `score` / `link` / `plan`), `resolve`,
-`bulk-update`, `dedupe`, `reassign`, `fix`, `health`,
+`hierarchy` (`report`), `relationships` (`account`),
+`route` (`leads`), `bulk-update`, `dedupe`, `reassign`, `fix`, `health`,
 `market` (`init` / `capture` / `classify` / `worksheet` / `observe` / `fronts` /
 `axes` / `overlay` / `scale` / `report` / `refresh`),
 `tam` (`estimate` / `accounts` / `status` / `report` / `populate`),
@@ -160,8 +161,8 @@ per-rule detail with capped examples, and next steps. `auditReportToMarkdown` /
 
 ## Governed write verbs
 
-Plan builders behind `bulk-update`, `dedupe`, and `reassign` — every one
-emits a standard dry-run `PatchPlan` for the normal approve → apply chain:
+Plan builders behind `route`, `bulk-update`, `dedupe`, and `reassign` — every
+one emits a standard dry-run `PatchPlan` for the normal approve → apply chain:
 
 - `buildBulkUpdatePlan(snapshot, options: BulkUpdateOptions)` with
   `parseWhere` (filter expressions: `=`, `!=`, `~`, `!~`, `:empty`,
@@ -179,6 +180,22 @@ emits a standard dry-run `PatchPlan` for the normal approve → apply chain:
   `assignUnowned` (CLI `--assign-unowned`) it targets ownerless records
   (`ownerId:empty`) and claims them for `--to` — the backfill twin of
   `enrich acquire`'s create-time assignment, for clearing existing ownerless debt.
+- `buildLeadRoutePlan(snapshot, options: LeadRouteOptions)` — matches contacts
+  to accounts by email domain and optional company-name fallback, skips free
+  email domains and ambiguous matches, then emits approval-gated account-link
+  and owner-assignment operations. Owner routing can inherit active account
+  owners for ownerless contacts or use the shared deterministic
+  `AssignmentPolicy`; existing owners are preserved unless
+  `reassignExistingOwner` (CLI `--reassign-owned`) is set.
+
+Read-only prevention reports:
+
+- `buildAccountHierarchy(snapshot)` / `accountHierarchyToMarkdown(report)` —
+  provider parent hints plus subdomain inference, with duplicate-domain,
+  ambiguous-parent, and parent-cycle conflicts surfaced rather than written.
+- `buildRelationshipMap(snapshot, { accountId | domain })` /
+  `relationshipMapToMarkdown(map)` — account stakeholders, inferred roles,
+  activity sentiment evidence, open deals, and missing-role gaps.
 
 `fix` is CLI-only composition of existing surfaces (audit → suggest →
 approve → apply for one rule).

package/docs/architecture.md

@@ -57,9 +57,12 @@ provider  ──fetchSnapshot()──►  CanonicalGtmSnapshot
 - `auditLog.ts` — hash-chained, signed export of every apply run.
 
 **Governed write verbs (each builds a plan; never writes directly)**
-- `bulkUpdate.ts`, `dedupe.ts`, `reassign.ts` — filtered/duplicate/ownership
-  plan builders. `merge.ts` — snapshot diff/merge + entity resolution.
+- `bulkUpdate.ts`, `dedupe.ts`, `reassign.ts`, `route.ts` — filtered,
+  duplicate, ownership handoff, and lead-to-account/owner routing plan builders.
+  `merge.ts` — snapshot diff/merge + entity resolution.
 - `resolve.ts` — the create-gate (exists / ambiguous / safe_to_create).
+- `hierarchy.ts`, `relationships.ts` — read-only account hierarchy and
+  stakeholder relationship-map reports for planning/prevention workflows.
 
 **Connectors** (`connectors/`)
 - `hubspot.ts`, `salesforce.ts`, `stripe.ts` + their `*Auth.ts` OAuth/device

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.47.0",
+  "version": "0.48.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 LLC <ryan@fullstackgtm.com> (https://fullstackgtm.com)",

package/skills/fullstackgtm/SKILL.md

@@ -94,7 +94,7 @@ Tools over stdio: `fullstackgtm_audit` (read-only), `fullstackgtm_rules`,
 This CLI ships governed **primitives** — there is no `outbound` mega-command.
 **You (the agent) are the orchestrator:** chain these verbs into the play the
 operator wants, surface the one approve gate, and bridge the last mile to the
-sender (**the package never sends**). [docs/recipes.md](https://github.com/fullstackgtm/core/blob/main/packages/fullstackgtm/docs/recipes.md)
+sender (**the package never sends**). [docs/recipes.md](https://github.com/fullstackgtm/core/blob/main/docs/recipes.md)
 has five worked plays — cold-start lead-fill, the trigger→judge→draft outbound
 loop, scheduled-continuous, ABM-from-companies, and hygiene-gated outbound.
 `fullstackgtm init` scaffolds a workspace (icp.json + enrich config + a PLAYBOOK
@@ -102,7 +102,7 @@ pointing at those recipes) to start from.
 
 ## Going deeper
 
-- [docs/recipes.md](https://github.com/fullstackgtm/core/blob/main/packages/fullstackgtm/docs/recipes.md) — five composable GTM plays over the primitives (cold-start, outbound loop, scheduled, ABM, hygiene-gated)
+- [docs/recipes.md](https://github.com/fullstackgtm/core/blob/main/docs/recipes.md) — five composable GTM plays over the primitives (cold-start, outbound loop, scheduled, ABM, hygiene-gated)
 - [llms.txt](https://github.com/fullstackgtm/core/blob/main/llms.txt) — the full invariant map per layer (calls, market, write verbs, enrich, schedule, engagement/health)
 - [INSTALL_FOR_AGENTS.md](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md) — deterministic install-and-verify with expected outputs
 - [docs/api.md](https://github.com/fullstackgtm/core/blob/main/docs/api.md) — semver-covered surfaces: canonical model, rule interface, plan/apply contract, connectors, config, CLI, MCP

package/src/audit.ts

@@ -9,6 +9,7 @@ import type {
   PipelineFindingType,
   PatchOperation,
   PatchPlan,
+  PatchPlanAssumption,
   SourceFreshness,
 } from "./types.ts";
 
@@ -53,6 +54,7 @@ export function auditSnapshot(
   const context = { snapshot, policy, index: buildSnapshotIndex(snapshot) };
   const findings: AuditFinding[] = [];
   const operations: PatchOperation[] = [];
+  const assumptionsById = new Map<string, PatchPlanAssumption>();
 
   for (const rule of rules) {
     try {
@@ -63,6 +65,9 @@ export function auditSnapshot(
     const result = rule.evaluate(context);
     findings.push(...result.findings);
     operations.push(...result.operations);
+    for (const assumption of result.assumptions ?? []) {
+      if (!assumptionsById.has(assumption.id)) assumptionsById.set(assumption.id, assumption);
+    }
     try {
       onRule?.(rule.id, "done", result.findings.length);
     } catch {
@@ -70,6 +75,7 @@ export function auditSnapshot(
     }
   }
 
+  const assumptions = Array.from(assumptionsById.values());
 
   const evidence = buildEvidence(snapshot, findings, policy.today);
   const pipelineFindings = buildPipelineFindings(findings, operations, evidence, policy.today);
@@ -85,6 +91,7 @@ export function auditSnapshot(
     findings,
     pipelineFindings,
     evidence,
+    assumptions: assumptions.length > 0 ? assumptions : undefined,
     operations,
   };
 }

package/src/backfill.ts

@@ -21,6 +21,7 @@ import type {
   PatchPlan,
 } from "./types.ts";
 import type { StripePaidInvoice } from "./connectors/stripe.ts";
+import { FREE_EMAIL_DOMAINS } from "./freeEmailDomains.ts";
 import { normalizeDomain } from "./merge.ts";
 
 // Mirrors stableHash in rules.ts (FNV-1a); duplicated to keep backfill.ts
@@ -36,22 +37,6 @@ function fnv1a(value: string): string {
 
 export const DEFAULT_BACKFILL_MATCH_PROPERTY = "stripe_invoice_id";
 
-// Freemail domains never become a company domain: stamping "gmail.com" on an
-// account (or resolving a company BY gmail.com) would collapse unrelated
-// customers onto one record. Mirrors FREE_MAIL in connectors/signalSources.ts
-// (duplicated to keep backfill.ts importable without connector code, the
-// fnv1a precedent above).
-const FREE_MAIL = new Set([
-  "gmail.com",
-  "yahoo.com",
-  "hotmail.com",
-  "outlook.com",
-  "icloud.com",
-  "aol.com",
-  "proton.me",
-  "protonmail.com",
-]);
-
 export type StripeBackfillOptions = {
   /** Pipeline id or case-insensitive label; absent = the portal's default pipeline. */
   pipeline?: string;
@@ -183,7 +168,7 @@ export function buildStripeBackfillPlan(
     let companyDomain = normalizeDomain(account?.domain);
     let accountIsNew = false;
     if (!account && createMissingAccounts) {
-      const usableDomain = domain && !FREE_MAIL.has(domain) ? domain : undefined;
+      const usableDomain = domain && !FREE_EMAIL_DOMAINS.has(domain) ? domain : undefined;
       const name = invoice.customerName?.trim() || usableDomain;
       if (name) {
         companyName = name;

package/src/cli/fix.ts

@@ -1,6 +1,6 @@
 // Extracted verbatim from src/cli.ts (mechanical split, no behavior change).
 
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { auditSnapshot, defaultPolicy } from "../audit.ts";
 import { loadConfig, mergePolicy, resolveConfiguredRules } from "../config.ts";
@@ -8,6 +8,10 @@ import { applyPatchPlan } from "../connector.ts";
 import { patchPlanToMarkdown } from "../format.ts";
 import { createFilePlanStore } from "../planStore.ts";
 import { resolveRecord, type ResolveCandidate } from "../resolve.ts";
+import { parseAssignmentPolicy } from "../assign.ts";
+import { buildLeadRoutePlan } from "../route.ts";
+import { accountHierarchyToMarkdown, buildAccountHierarchy } from "../hierarchy.ts";
+import { buildRelationshipMap, relationshipMapToMarkdown } from "../relationships.ts";
 import { buildBulkUpdatePlan } from "../bulkUpdate.ts";
 import { buildDedupePlan, type DedupeOptions } from "../dedupe.ts";
 import { buildReassignPlans, type ReassignObjectType } from "../reassign.ts";
@@ -371,3 +375,66 @@ function snapshotSourceHint(args: string[]) {
   if (input) return `--input ${input} `;
   return "";
 }
+
+function parseJsonOrFile(value: string): unknown {
+  const candidate = resolve(process.cwd(), value);
+  const text = existsSync(candidate) ? readFileSync(candidate, "utf8") : value;
+  return JSON.parse(text);
+}
+
+export async function routeCommand(args: string[]) {
+  const [subcommand, ...rest] = args;
+  if (subcommand !== "leads") {
+    throw new Error("Usage: fullstackgtm route leads [source options] [--match domain|company|both] [--no-inherit-owner] [--reassign-owned] [--policy <json|path>] [--save] [--json] [--out <path>]");
+  }
+  const match = option(rest, "--match") ?? "domain";
+  if (!["domain", "company", "both"].includes(match)) throw new Error("--match must be domain, company, or both");
+  const policyRaw = option(rest, "--policy");
+  const snapshot = await readSnapshot(rest);
+  const result = buildLeadRoutePlan(snapshot, {
+    matchByDomain: match === "domain" || match === "both",
+    matchByCompanyName: match === "company" || match === "both",
+    inheritAccountOwner: !rest.includes("--no-inherit-owner"),
+    reassignExistingOwner: rest.includes("--reassign-owned"),
+    assignmentPolicy: policyRaw ? parseAssignmentPolicy(parseJsonOrFile(policyRaw)) : undefined,
+    maxOperations: numericOption(rest, "--max-operations"),
+    reason: option(rest, "--reason") ?? undefined,
+  });
+  if (rest.includes("--json")) {
+    const out = option(rest, "--out");
+    if (out) writeFileSync(resolve(process.cwd(), out), `${JSON.stringify(result.plan, null, 2)}\n`);
+    if (saveRequested(rest)) await createFilePlanStore().save(result.plan);
+    console.error(`Route dry-run: ${JSON.stringify(result.counts)}`);
+    console.log(JSON.stringify({ counts: result.counts, plan: result.plan }, null, 2));
+    return;
+  }
+  console.error(
+    `Route dry-run: ${result.counts.linkOperations} link(s), ${result.counts.ownerOperations} owner assignment(s), ${result.counts.ambiguousAccountMatches} ambiguous match(es).`,
+  );
+  await emitPlan(result.plan, rest);
+}
+
+export async function hierarchyCommand(args: string[]) {
+  const [subcommand, ...rest] = args;
+  if (subcommand !== "report") throw new Error("Usage: fullstackgtm hierarchy report [source options] [--json|--out <path>]");
+  const snapshot = await readSnapshot(rest);
+  const report = buildAccountHierarchy(snapshot);
+  const out = option(rest, "--out");
+  const rendered = rest.includes("--json") ? `${JSON.stringify(report, null, 2)}\n` : `${accountHierarchyToMarkdown(report)}\n`;
+  if (out) writeFileSync(resolve(process.cwd(), out), rendered);
+  console.log(rendered.trimEnd());
+}
+
+export async function relationshipsCommand(args: string[]) {
+  const [subcommand, ...rest] = args;
+  if (subcommand !== "account") throw new Error("Usage: fullstackgtm relationships account (--account-id <id>|--domain <d>) [source options] [--json|--out <path>]");
+  const accountId = option(rest, "--account-id") ?? undefined;
+  const domain = option(rest, "--domain") ?? undefined;
+  if (!accountId && !domain) throw new Error("relationships account needs --account-id <id> or --domain <domain>");
+  const snapshot = await readSnapshot(rest);
+  const map = buildRelationshipMap(snapshot, { accountId, domain });
+  const out = option(rest, "--out");
+  const rendered = rest.includes("--json") ? `${JSON.stringify(map, null, 2)}\n` : `${relationshipMapToMarkdown(map)}\n`;
+  if (out) writeFileSync(resolve(process.cwd(), out), rendered);
+  console.log(rendered.trimEnd());
+}