fullstackgtm 0.42.0 → 0.44.0

package/src/health.ts

@@ -35,6 +35,18 @@ export type HealthEntry = {
   byRule: Record<string, number>;
   /** Finding count per severity. */
   severityCounts: Record<AuditFindingSeverity, number>;
+  /**
+   * Per-object-type breakdown — so "is my contact data clean but my pipeline
+   * messy?" is answerable without re-auditing. Each type carries its own
+   * record-normalized score (same curve as the overall score, scoped to that
+   * type's records + findings).
+   */
+  byObjectType: Record<"account" | "contact" | "deal", {
+    records: number;
+    findings: number;
+    weightedFindings: number;
+    score: number;
+  }>;
 };
 
 export type HealthRuleDelta = {
@@ -68,11 +80,21 @@ export type HealthRollup = {
 export function computeHealth(plan: PatchPlan, snapshot: CanonicalGtmSnapshot, at: string): HealthEntry {
   const byRule: Record<string, number> = {};
   const severityCounts: Record<AuditFindingSeverity, number> = { info: 0, warning: 0, critical: 0 };
+  const typeTally: Record<"account" | "contact" | "deal", { findings: number; weightedFindings: number }> = {
+    account: { findings: 0, weightedFindings: 0 },
+    contact: { findings: 0, weightedFindings: 0 },
+    deal: { findings: 0, weightedFindings: 0 },
+  };
   let weightedFindings = 0;
   for (const finding of plan.findings) {
     byRule[finding.ruleId] = (byRule[finding.ruleId] ?? 0) + 1;
     severityCounts[finding.severity] += 1;
     weightedFindings += SEVERITY_WEIGHT[finding.severity];
+    const t = finding.objectType;
+    if (t === "account" || t === "contact" || t === "deal") {
+      typeTally[t].findings += 1;
+      typeTally[t].weightedFindings += SEVERITY_WEIGHT[finding.severity];
+    }
   }
 
   const records = {
@@ -82,8 +104,23 @@ export function computeHealth(plan: PatchPlan, snapshot: CanonicalGtmSnapshot, a
     total: snapshot.accounts.length + snapshot.contacts.length + snapshot.deals.length,
   };
 
-  const penalty = weightedFindings / Math.max(records.total, 1);
-  const score = Math.round(100 / (1 + penalty));
+  const scoreFor = (weighted: number, recordCount: number) =>
+    Math.round(100 / (1 + weighted / Math.max(recordCount, 1)));
+  const recordsByType = { account: records.accounts, contact: records.contacts, deal: records.deals };
+  const byObjectType = (["account", "contact", "deal"] as const).reduce(
+    (acc, t) => {
+      acc[t] = {
+        records: recordsByType[t],
+        findings: typeTally[t].findings,
+        weightedFindings: typeTally[t].weightedFindings,
+        score: scoreFor(typeTally[t].weightedFindings, recordsByType[t]),
+      };
+      return acc;
+    },
+    {} as HealthEntry["byObjectType"],
+  );
+
+  const score = scoreFor(weightedFindings, records.total);
 
   return {
     at,
@@ -94,6 +131,7 @@ export function computeHealth(plan: PatchPlan, snapshot: CanonicalGtmSnapshot, a
     records,
     byRule,
     severityCounts,
+    byObjectType,
   };
 }
 
@@ -155,6 +193,13 @@ export function healthToMarkdown(rollup: HealthRollup): string {
     "",
   );
 
+  lines.push("## By object type", "", "| Type | Score | Findings | Records |", "| --- | --- | --- | --- |");
+  for (const t of ["account", "contact", "deal"] as const) {
+    const b = current.byObjectType[t];
+    lines.push(`| ${t} | ${b.score}/100 | ${b.findings} | ${b.records} |`);
+  }
+  lines.push("");
+
   if (rollup.history.length > 1) {
     lines.push("## Trend", "");
     for (const point of rollup.history) {

package/src/icp.ts

@@ -24,6 +24,10 @@ export type Icp = {
     employeeBands?: string[];
     /** ISO country codes, lowercased, e.g. ["us"] */
     geos?: string[];
+    /** technographic targeting: technology slugs the account must use, e.g.
+     *  ["salesforce","hubspot","pipedrive"] — the real CRM/MAP buying signal,
+     *  consumed by TheirStack company search. OR-matched. */
+    technologies?: string[];
   };
   persona: {
     /** seniority: "cxo","vp","director","manager","owner","senior" */
@@ -79,6 +83,81 @@ export function icpToExploriumFilters(icp: Icp): Record<string, { values?: strin
   return f;
 }
 
+/**
+ * Explorium /v1/businesses filters from the ICP — the COMPANY (account) side, for
+ * sizing the account universe (TAM). Firmographics only, no persona: the count is
+ * of matching companies. Field names differ from /v1/prospects (verified live):
+ * `country_code` (not company_country_code), `company_size` (same employee bands),
+ * `naics_category`. `/v1/businesses` total_results is a real count, capped at
+ * 60,000 (see EXPLORIUM_BUSINESS_COUNT_CAP in the connector).
+ */
+export function icpToExploriumBusinessFilters(icp: Icp): Record<string, { values?: string[] }> {
+  const f: Record<string, { values?: string[] }> = {};
+  if (icp.firmographics.geos?.length) f.country_code = { values: icp.firmographics.geos };
+  if (icp.firmographics.employeeBands?.length) f.company_size = { values: icp.firmographics.employeeBands };
+  if (icp.firmographics.naics?.length) f.naics_category = { values: icp.firmographics.naics };
+  return f;
+}
+
+/**
+ * Collapse provider-agnostic employee bands ("51-200","10001+") into a single
+ * {min,max} envelope for APIs that take integer bounds (TheirStack). An open
+ * top band ("10001+") leaves max undefined.
+ */
+export function employeeBandsToRange(bands: string[] | undefined): { min?: number; max?: number } {
+  if (!bands?.length) return {};
+  let min: number | undefined;
+  let max: number | undefined;
+  let openTop = false;
+  for (const band of bands) {
+    const plus = /^(\d+)\+$/.exec(band.trim());
+    if (plus) {
+      const lo = Number(plus[1]);
+      if (min === undefined || lo < min) min = lo;
+      openTop = true;
+      continue;
+    }
+    const range = /^(\d+)\s*-\s*(\d+)$/.exec(band.trim());
+    if (range) {
+      const lo = Number(range[1]);
+      const hi = Number(range[2]);
+      if (min === undefined || lo < min) min = lo;
+      if (max === undefined || hi > max) max = hi;
+    }
+  }
+  return { min, max: openTop ? undefined : max };
+}
+
+/**
+ * TheirStack company-search filter from the ICP: the technographic targeting that
+ * Explorium can't do. `company_technology_slug_or` is the CRM/MAP buying signal
+ * (firmographics.technologies); employee bands become min/max bounds; geos become
+ * ISO2 codes (uppercased).
+ */
+export function icpToTheirStackFilters(icp: Icp): {
+  company_technology_slug_or?: string[];
+  min_employee_count?: number;
+  max_employee_count?: number;
+  company_country_code_or?: string[];
+} {
+  const f: {
+    company_technology_slug_or?: string[];
+    min_employee_count?: number;
+    max_employee_count?: number;
+    company_country_code_or?: string[];
+  } = {};
+  if (icp.firmographics.technologies?.length) {
+    f.company_technology_slug_or = icp.firmographics.technologies.map((t) => t.trim().toLowerCase());
+  }
+  if (icp.firmographics.geos?.length) {
+    f.company_country_code_or = icp.firmographics.geos.map((g) => g.trim().toUpperCase());
+  }
+  const range = employeeBandsToRange(icp.firmographics.employeeBands);
+  if (range.min !== undefined) f.min_employee_count = range.min;
+  if (range.max !== undefined) f.max_employee_count = range.max;
+  return f;
+}
+
 /**
  * Crustdata / LinkedIn seniority vocab. ICP job levels are normalized lowercase;
  * Crustdata expects these exact capitalized strings (verified: "CXO",
@@ -101,16 +180,31 @@ const CRUSTDATA_SENIORITY: Record<string, string> = {
 };
 
 /**
- * ICP industry keyword → LinkedIn industry names Crustdata filters on. Includes
- * the current LinkedIn-v2 names; for software we send the cluster (dev + IT
- * services + internet) so an OR match isn't overly narrow.
+ * ICP industry keyword → LinkedIn industry names Crustdata filters on.
+ *
+ * LinkedIn renamed its industry taxonomy (v1 → v2, ~2022), and data vendors
+ * normalize to one generation or the other. Sending ONLY the v2 names risks a
+ * zero-match when Crustdata stores v1 (and vice-versa) — observed live: a RevOps
+ * ICP whose only firmographic constraint was the v2 names returned 0 even though
+ * the title-only search returned plenty. So each cluster sends BOTH generations
+ * (OR-matched within the field): v2 ("Software Development", "IT Services and IT
+ * Consulting", "Technology, Information and Internet") AND v1 ("Computer
+ * Software", "Information Technology & Services", "Internet").
  */
 const CRUSTDATA_INDUSTRY: Record<string, string[]> = {
-  software: ["Software Development", "Information Technology and Services", "Internet"],
-  saas: ["Software Development", "Information Technology and Services"],
-  "information technology & services": ["Information Technology and Services"],
-  "information technology and services": ["Information Technology and Services"],
-  internet: ["Internet"],
+  software: [
+    "Software Development",
+    "Computer Software",
+    "IT Services and IT Consulting",
+    "Information Technology & Services",
+    "Information Technology and Services",
+    "Technology, Information and Internet",
+    "Internet",
+  ],
+  saas: ["Software Development", "Computer Software", "IT Services and IT Consulting", "Information Technology & Services"],
+  "information technology & services": ["Information Technology & Services", "IT Services and IT Consulting"],
+  "information technology and services": ["Information Technology & Services", "IT Services and IT Consulting"],
+  internet: ["Internet", "Technology, Information and Internet"],
   fintech: ["Financial Services"],
   "financial services": ["Financial Services"],
 };
@@ -119,9 +213,17 @@ const CRUSTDATA_INDUSTRY: Record<string, string[]> = {
  * pipe0 Crustdata people-search config.filters from the ICP. `current_job_titles`
  * matches real LinkedIn title strings (case-sensitive), so keywords are Title
  * Cased. Seniority + industry are mapped to Crustdata's controlled vocab via the
- * tables above. NOTE: the exact pipe0→Crustdata value set could not be re-run
- * live (pipe0 credits were exhausted) — validate when credits refill; fit
- * scoring is the safety net for persona precision regardless.
+ * tables above.
+ *
+ * LIVE FINDINGS (2026-06-26): `current_job_titles` is confirmed working (a
+ * titles-only RevOps search returns results); `current_title` is rejected (422).
+ * The full ICP filter returned 0 — the prime suspect is the industry vocab
+ * (LinkedIn v1/v2 taxonomy mismatch), now hedged by sending BOTH generations in
+ * CRUSTDATA_INDUSTRY above. NOT yet re-confirmed end-to-end (pipe0 credits were
+ * exhausted mid-investigation) — re-run `enrich acquire --source pipe0` once
+ * credits refill; if it still returns 0, the next suspects are the
+ * `current_seniority_levels` shape/values and `locations`. Note fit-scoring backs
+ * up PERSONA precision but NOT industry, so the industry filter is load-bearing.
  */
 export function icpToCrustdataFilters(icp: Icp): Record<string, unknown> {
   const f: Record<string, unknown> = {};

package/src/index.ts

@@ -97,6 +97,48 @@ export {
   type EnrichWorkItem,
   type MatchOutcome,
 } from "./enrich.ts";
+export {
+  scaffoldWorkspace,
+  starterEnrichConfig,
+  starterIcp,
+  starterPlaybook,
+  type InitProvider,
+  type InitSource,
+  type ScaffoldFile,
+  type ScaffoldOptions,
+} from "./init.ts";
+export {
+  appendCoverage,
+  classifyAccount,
+  classifyCoverage,
+  computeCoverage,
+  coverageCountsFromSnapshot,
+  coveredAccounts,
+  coverageToText,
+  crmCheckableCriteria,
+  deriveAcvFromClosedWon,
+  deriveBuyersPerAccount,
+  estimateTam,
+  loadTamModel,
+  projectEta,
+  readCoverageTimeline,
+  saveTamModel,
+  tamDir,
+  tamReportToMarkdown,
+  type AccountTamClass,
+  type AcvBasis,
+  type DerivedAcv,
+  type DerivedBuyers,
+  type EstimateTamInput,
+  type TamClassified,
+  type TamCoverage,
+  type TamCoverageCounts,
+  type TamCrossCheck,
+  type TamEta,
+  type TamModel,
+  type TamTargeting,
+  type TamUniverse,
+} from "./tam.ts";
 export {
   apolloPullKeysForAppend,
   apolloPullKeysForRefresh,

package/src/init.ts

@@ -0,0 +1,166 @@
+/**
+ * `fullstackgtm init` — scaffold a GTM workspace from cold scratch.
+ *
+ * The product thesis (see docs/recipes.md): the CLI ships governed PRIMITIVES;
+ * the user's coding agent is the orchestrator. There is deliberately no
+ * `outbound` mega-verb. `init` is the one piece of scaffolding that earns its
+ * keep — it writes the three files a workspace needs so the very first
+ * `enrich acquire` / `signals` / `judge` / `draft` commands work, plus a
+ * PLAYBOOK that points at the recipes wired with THIS workspace's source and
+ * provider.
+ *
+ * It is a pure file-writer: no network, no credentials, never overwrites
+ * without `--force`. The starter ICP is a valid (editable) example so
+ * `icp show` / `enrich acquire` run immediately; re-run `icp interview` to
+ * replace it with a real one.
+ */
+
+import { builtinAcquirePreset, ENRICH_CONFIG_FILE_NAME, type EnrichConfig } from "./enrich.ts";
+import { DEFAULT_FIT_THRESHOLD, type Icp } from "./icp.ts";
+
+export type InitProvider = "hubspot" | "salesforce";
+export type InitSource = "pipe0" | "explorium" | "linkedin";
+
+export type ScaffoldOptions = {
+  /** discovery source the acquire preset + playbook are wired for. Default "pipe0". */
+  source?: InitSource;
+  /** CRM the playbook writes against. Default "hubspot". */
+  provider?: InitProvider;
+  /** profile the playbook scopes commands to (omitted = default profile). */
+  profile?: string;
+};
+
+export type ScaffoldFile = { path: string; content: string };
+
+/** A placeholder owner id that can never match a real one, so the assign block
+ *  is VISIBLE (leads route through it) yet safe: an unknown owner resolves to
+ *  unassigned with a warning, never a wrong owner. Replace before acquiring. */
+const PLACEHOLDER_OWNER = "REPLACE_WITH_OWNER_ID";
+
+/** A generic, valid starter ICP. Edit it, or replace via `icp interview`. */
+export function starterIcp(): Icp {
+  return {
+    name: "Example ICP — edit me (or rebuild with `fullstackgtm icp interview`)",
+    firmographics: {
+      industries: ["software", "saas"],
+      employeeBands: ["51-200", "201-500", "501-1000"],
+      geos: ["us"],
+      // Technographic targeting (the real RevOps signal): companies that USE a
+      // CRM/MAP. Drives `tam estimate|accounts --source theirstack`.
+      technologies: ["salesforce", "hubspot", "pipedrive"],
+    },
+    persona: {
+      jobLevels: ["vp", "director", "manager"],
+      departments: ["sales", "operations"],
+      titleKeywords: ["revenue operations", "revops", "sales operations", "gtm operations"],
+    },
+    scoring: { threshold: DEFAULT_FIT_THRESHOLD },
+  };
+}
+
+/** The acquire preset for the chosen source, with an explicit (placeholder)
+ *  assign policy so the seam is visible — leads are never silently ownerless. */
+export function starterEnrichConfig(source: InitSource): EnrichConfig {
+  const preset = builtinAcquirePreset(source);
+  if (!preset?.acquire) {
+    // builtinAcquirePreset covers pipe0/explorium/linkedin, so this is unreachable
+    // for the typed InitSource set — guard anyway rather than emit a broken file.
+    throw new Error(`init: no acquire preset for source "${source}"`);
+  }
+  return {
+    ...preset,
+    acquire: { ...preset.acquire, assign: { strategy: "fixed", ownerId: PLACEHOLDER_OWNER } },
+  };
+}
+
+function profileFlag(profile?: string): string {
+  return profile ? ` --profile ${profile}` : "";
+}
+
+/** The workspace PLAYBOOK: the cold-start + outbound-loop recipes wired with the
+ *  chosen source/provider/profile, pointing at docs/recipes.md for the rest. */
+export function starterPlaybook(opts: Required<Pick<ScaffoldOptions, "source" | "provider">> & { profile?: string }): string {
+  const { source, provider, profile } = opts;
+  const p = profileFlag(profile);
+  const loginSource = source === "linkedin" ? "heyreach" : source;
+  return `# Workspace playbook
+
+Scaffolded by \`fullstackgtm init\` for **${provider}**, discovery via **${source}**${
+    profile ? `, profile **${profile}**` : ""
+  }.
+
+This CLI ships governed **primitives** — there is no \`outbound\` command. **You
+(the coding agent) are the orchestrator:** chain the verbs into the play the
+operator wants, surface the one approve gate, and bridge the last mile to the
+sender. **The package never sends** — \`draft\` produces an approved task/opener;
+the actual send happens in the operator's own channel tool.
+
+Full recipe set: **docs/recipes.md** (cold-start, the trigger→judge→draft
+outbound loop, scheduled-continuous, ABM-from-companies, hygiene-gated).
+
+## 0. Connect (secrets via stdin/env, never argv)
+
+\`\`\`bash
+echo "$${provider === "hubspot" ? "HUBSPOT_TOKEN" : "SALESFORCE_ACCESS_TOKEN"}" | fullstackgtm login ${provider}${p}
+echo "$${loginSource.toUpperCase()}_API_KEY" | fullstackgtm login ${loginSource}${p}
+\`\`\`
+
+## 1. Edit your targeting + assignment
+
+- \`icp.json\` — the starter ICP. Edit it, or rebuild: \`fullstackgtm icp interview\`
+  (an agent drives the questions) → \`fullstackgtm icp set answers.json\`.
+- \`${ENRICH_CONFIG_FILE_NAME}\` — set \`acquire.assign.ownerId\` (currently
+  \`${PLACEHOLDER_OWNER}\`) so acquired leads are never ownerless, or pass
+  \`--assign-owner <id>\` per run. Tune \`acquire.budget\` (records + spend caps).
+
+## 2. Cold start — fill the CRM with targeted, owned, emailed leads
+
+\`\`\`bash
+fullstackgtm enrich acquire --source ${source} --provider ${provider}${p} --json   # dry-run plan, writes NOTHING
+fullstackgtm enrich acquire --source ${source} --provider ${provider}${p} --save    # persist as needs_approval
+fullstackgtm plans approve <plan-id>${p} --operations all
+fullstackgtm apply --plan-id <plan-id> --provider ${provider}${p}
+\`\`\`
+
+Each lead lands owner-stamped and linked to a domain-stamped **account**, so the
+signals/judge layer can watch it.
+
+## 3. Outbound loop — reach an account the week something changes
+
+\`\`\`bash
+fullstackgtm signals fetch --bucket job,funding --watchlist crm:<segment>${p} --save
+fullstackgtm icp judge --signals-from latest --provider ${provider}${p} --save --json   # pass the snapshot → resolves accountId + contact
+fullstackgtm draft --from-judge latest --channel email${p} --save --json                # one grounded opener per hot account, as a create_task
+fullstackgtm plans approve <plan-id>${p} --operations all
+fullstackgtm apply --plan-id <plan-id> --provider ${provider}${p}
+# → the agent sends the approved opener via the operator's channel tool, then:
+fullstackgtm signals outcome --account <domain> --contact <contactId> --result replied${p}
+\`\`\`
+
+A domain-only judge decision (account not yet in the CRM) is rejected by \`draft\`
+with "acquire it first" — run step 2 for that account, then re-judge.
+
+## The boundary
+
+- **Read freely. Write only through \`plans approve → apply\`.**
+- **The package never sends.** \`draft\` is the last governed step.
+- **You are the orchestrator.** These are starting points — compose them.
+`;
+}
+
+/**
+ * Build the set of files `init` would write (pure — no IO). The caller decides
+ * which to actually write (skipping existing files unless --force).
+ */
+export function scaffoldWorkspace(opts: ScaffoldOptions = {}): ScaffoldFile[] {
+  const source: InitSource = opts.source ?? "pipe0";
+  const provider: InitProvider = opts.provider ?? "hubspot";
+  return [
+    { path: "icp.json", content: `${JSON.stringify(starterIcp(), null, 2)}\n` },
+    {
+      path: ENRICH_CONFIG_FILE_NAME,
+      content: `${JSON.stringify(starterEnrichConfig(source), null, 2)}\n`,
+    },
+    { path: "PLAYBOOK.md", content: starterPlaybook({ source, provider, profile: opts.profile }) },
+  ];
+}

package/src/judge.ts

@@ -35,6 +35,23 @@ export type JudgeDecisionKind = "send" | "nurture" | "skip";
 
 export type JudgeDecision = {
   accountDomain: string;
+  /**
+   * The CRM account this domain resolves to, when a snapshot was provided.
+   * Absent = the account is not in the CRM (a net-new domain) — downstream
+   * verbs must acquire it before they can write against it.
+   */
+  accountId?: string;
+  /**
+   * The contact at the account to reach, when resolvable from the snapshot —
+   * the answer to "who do I message at this hot account". `draft` targets this
+   * contact's id; absent contact + present accountId targets the account.
+   */
+  contact?: ContactRef;
+  /**
+   * All in-CRM contacts at the account (primary first), capped — so an agent can
+   * multi-thread beyond the single primary. `contact` is `contacts[0]`.
+   */
+  contacts?: ContactRef[];
   /** 0-100. */
   score: number;
   decision: JudgeDecisionKind;
@@ -333,22 +350,75 @@ export function accountRecentlyTouched(
 }
 
 /**
- * Find the best-matching contact for an account from the snapshot, for fit
- * scoring: the account's contacts, preferring one with a title (a title is what
- * fit scores on). Returns undefined when the account/contact isn't in snapshot.
+ * Resolve a signal's account domain to the CRM account record and the best
+ * contact at it (preferring one with a title). The single domain→account→contact
+ * join used by both fit scoring and target surfacing — so "who do I message at
+ * this account" is computed once and consistently.
  */
-export function bestContactForAccount(
+function findAccountAndBestContact(
   accountDomain: string,
   snapshot: CanonicalGtmSnapshot,
-): { jobTitle?: string; jobLevel?: string; jobDepartment?: string; headline?: string } | undefined {
+): {
+  account: CanonicalGtmSnapshot["accounts"][number];
+  contact?: CanonicalGtmSnapshot["contacts"][number];
+  contacts: CanonicalGtmSnapshot["contacts"];
+} | undefined {
   const domain = normalizeAccountDomain(accountDomain);
   if (!domain) return undefined;
   const account = (snapshot.accounts ?? []).find((a) => normalizeAccountDomain(a.domain ?? "") === domain);
   if (!account) return undefined;
-  const contacts = (snapshot.contacts ?? []).filter((c) => c.accountId === account.id);
-  const withTitle = contacts.find((c) => c.title) ?? contacts[0];
-  if (!withTitle) return undefined;
-  return { jobTitle: withTitle.title };
+  // Titled contacts first (a title is what fit scores on); the first is primary.
+  const contacts = (snapshot.contacts ?? [])
+    .filter((c) => c.accountId === account.id)
+    .sort((a, b) => (b.title ? 1 : 0) - (a.title ? 1 : 0));
+  return { account, contact: contacts[0], contacts };
+}
+
+/**
+ * Best-matching contact for an account, shaped for fit scoring (the title is
+ * what `scoreProspectAgainstIcp` reads). Returns undefined when the
+ * account/contact isn't in the snapshot.
+ */
+export function bestContactForAccount(
+  accountDomain: string,
+  snapshot: CanonicalGtmSnapshot,
+): { jobTitle?: string; jobLevel?: string; jobDepartment?: string; headline?: string } | undefined {
+  const found = findAccountAndBestContact(accountDomain, snapshot);
+  if (!found?.contact) return undefined;
+  return { jobTitle: found.contact.title };
+}
+
+/**
+ * Resolve the CRM target for an account domain: its `accountId` (when the
+ * account exists in the snapshot) and the best `contact` to reach (id + email +
+ * title). This is what `draft` writes against — a real record id, never the
+ * domain. `{}` when the account is not in the CRM (a net-new domain).
+ */
+export type ContactRef = { id: string; email?: string; title?: string };
+
+/** Cap on candidate contacts surfaced per account (the rest stay in the CRM). */
+const MAX_CANDIDATE_CONTACTS = 10;
+
+const toContactRef = (c: CanonicalGtmSnapshot["contacts"][number]): ContactRef => ({
+  id: c.id,
+  ...(c.email ? { email: c.email } : {}),
+  ...(c.title ? { title: c.title } : {}),
+});
+
+export function resolveAccountTarget(
+  accountDomain: string,
+  snapshot: CanonicalGtmSnapshot,
+): { accountId?: string; contact?: ContactRef; contacts?: ContactRef[] } {
+  const found = findAccountAndBestContact(accountDomain, snapshot);
+  if (!found) return {};
+  const { account, contact, contacts } = found;
+  return {
+    accountId: account.id,
+    ...(contact ? { contact: toContactRef(contact) } : {}),
+    // The candidate contacts at the account, so an agent can multi-thread
+    // beyond the single primary. Capped; primary is contacts[0].
+    ...(contacts.length ? { contacts: contacts.slice(0, MAX_CANDIDATE_CONTACTS).map(toContactRef) } : {}),
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -559,10 +629,11 @@ export async function judgeSignals(opts: {
 
   const decisions: JudgeDecision[] = [];
   for (const [domain, signals] of byAccount) {
+    // Memory + fit stay gated on --with-history (scoring semantics unchanged).
     const recentlyTouched =
       opts.withHistory && opts.snapshot ? accountRecentlyTouched(domain, opts.snapshot, now) : false;
     const bestContact =
-      opts.icp && opts.snapshot ? bestContactForAccount(domain, opts.snapshot) : undefined;
+      opts.withHistory && opts.icp && opts.snapshot ? bestContactForAccount(domain, opts.snapshot) : undefined;
     const score = scoreAccount({
       accountDomain: domain,
       signals,
@@ -578,7 +649,10 @@ export async function judgeSignals(opts: {
       opts.llm && opts.promptTemplate
         ? await judgeDecisionLlm(score, opts.promptTemplate, opts.llm)
         : deterministicDecision(score);
-    decisions.push(decision);
+    // Surface the CRM target (accountId + best contact) whenever a snapshot is
+    // present — independent of --with-history. This is what makes a decision
+    // actionable: draft writes against contact.id / accountId, never the domain.
+    decisions.push(opts.snapshot ? { ...decision, ...resolveAccountTarget(domain, opts.snapshot) } : decision);
   }
 
   return decisions.sort((a, b) => b.score - a.score || a.accountDomain.localeCompare(b.accountDomain));

package/src/judgeEval.ts

@@ -205,7 +205,14 @@ export function defaultJudgeFn(opts: { config?: SignalsConfig; icp?: Icp; now?:
 // ---------------------------------------------------------------------------
 // The default golden set (ships inline so `icp eval --golden default` is free)
 
-const GOLD_NOW_ISO = "2026-06-23T12:00:00.000Z";
+/**
+ * The default golden set's clock. Every `firstSeen` below is relative to this
+ * instant, so grading MUST pin `now: new Date(DEFAULT_GOLDEN_NOW_ISO)` —
+ * grading against wall time lets freshness decay rot the "fresh → send" rows,
+ * and the gate starts failing on a calendar date instead of a code change.
+ */
+export const DEFAULT_GOLDEN_NOW_ISO = "2026-06-23T12:00:00.000Z";
+const GOLD_NOW_ISO = DEFAULT_GOLDEN_NOW_ISO;
 
 function goldSignal(over: {
   accountDomain: string;

package/src/runReport.ts

@@ -11,7 +11,34 @@ import { getCredential } from "./credentials.ts";
 
 type RunEvent = { ts: number; type: string; detail?: string };
 
+/**
+ * Per-row finding for the hosted run timeline. IDs + issue type ONLY — no field
+ * values ever leave the CLI, keeping the audit's row data on the operator's side
+ * while still giving the dashboard navigable, filterable detail.
+ */
+export type RunFinding = {
+  objectType: string;
+  objectId: string;
+  severity: string;
+  ruleId: string;
+  field?: string;
+  operation?: string;
+};
+
+/**
+ * Where a run's findings live in the source CRM, so the dashboard can deep-link
+ * each record. `recordUrlBase` is the provider's record URL prefix; the
+ * dashboard appends the per-object path. Just an URL prefix — no record data.
+ */
+export type RunCrm = { provider: string; recordUrlBase: string };
+
+// Bound the fire-and-forget POST: a pathological audit could surface thousands
+// of findings; cap what we ship (counts still carry the true total).
+const MAX_REPORTED_FINDINGS = 2000;
+
 let counts: Record<string, unknown> | undefined;
+let findings: RunFinding[] | undefined;
+let crm: RunCrm | undefined;
 const events: RunEvent[] = [];
 
 /** A command annotates its headline metrics (merged). */
@@ -19,6 +46,16 @@ export function reportCounts(values: Record<string, unknown>): void {
   counts = { ...(counts ?? {}), ...values };
 }
 
+/** A command reports per-row findings (IDs + issue type, no values). */
+export function reportFindings(values: RunFinding[]): void {
+  findings = values.slice(0, MAX_REPORTED_FINDINGS);
+}
+
+/** A command reports the source CRM's record-URL base for dashboard deep-links. */
+export function reportCrm(value: RunCrm): void {
+  crm = value;
+}
+
 /** A command annotates a structured event (plan saved, meter charged, …). */
 export function reportEvent(type: string, detail?: string): void {
   events.push({ ts: Date.now(), type, detail });
@@ -65,6 +102,8 @@ export async function flushRunReport(
         finishedAt,
         durationMs: finishedAt - startedAt,
         counts,
+        findings: findings?.length ? findings : undefined,
+        crm,
         events: events.length ? events : undefined,
         error,
       }),