fullstackgtm 0.34.0 → 0.37.0

package/CHANGELOG.md

@@ -5,6 +5,97 @@ 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.37.0] — 2026-06-19
+
+### Added
+
+- **`enrich acquire` — net-new, ICP-targeted, deduped, metered lead generation
+  into the CRM.** Where `enrich append/refresh` fill blanks on records that
+  already exist, `acquire` discovers net-new people, resolves their work email,
+  and proposes governed `create_record` operations through the existing
+  dry-run → approve → apply gate. Never auto-writes.
+  - **`create_record` operation** + resolve-first contact creation in the
+    HubSpot connector (re-checks the dedupe key at apply, never double-creates).
+  - **Acquire meter** (`acquireMeter.ts`): per-profile windowed budget capping
+    both record count and provider spend (per-day + per-month, whichever binds
+    first); charged only for creates that land at apply.
+  - **ICP artifact** (`icp.ts`) + **`icp interview` / `icp set` / `icp show`**:
+    one profile drives per-provider discovery filters (Explorium + pipe0/Crustdata)
+    AND fit-scores every prospect — only above-threshold leads are proposed.
+    `icp interview` emits a question spec an agent drives with AskUserQuestion.
+  - **API prospect sources** (`connectors/prospectSources.ts`): Explorium
+    discovery, pipe0 work-email waterfall (chunked, surfaces upstream errors),
+    and pipe0/Crustdata people search.
+  - **No paying for dupes**: pre-email dedup against the live CRM snapshot +
+    a cross-run **seen cache** (`acquireSeen.ts`) drop already-known prospects
+    *before* the paid email step. **LinkedIn URL (`hs_linkedin_url`) is now read
+    into the snapshot** as the strong dedup key (safe everywhere — HubSpot
+    ignores unknown properties); created contacts write it back, so dedup
+    strengthens over time. A recommendation fires when the CRM has none.
+  - **Zero-config preset**: `enrich acquire` works with only an `icp.json` and
+    `login` — sensible defaults for budget, provider, and create-mapping.
+  - **`login pipe0` / `login explorium`** credential flow.
+
+### Also
+
+- Built-in **clay enrich preset** + `enrich ingest <csv> --source clay --input`
+  one-shot (stage → match in one command).
+
+## [0.36.0] — 2026-06-19
+
+### Added
+
+- **Engagement workspace — a per-client CRM health timeline.** The profile dir
+  (`$FSGTM_HOME[/profiles/<name>]`) becomes a continuous record, not just a place
+  for credentials and plans: every `audit --save` now stamps a deterministic
+  hygiene score and a snapshot onto the profile, so a consultant working
+  `--profile <client>` accrues that org's health over time from the verb they
+  already run.
+  - **`fullstackgtm health [--json]`** (new, read-only) rolls up the timeline:
+    current score, the change since the last audit, a dated trend, and per-rule
+    finding deltas. Empty timeline prints a pointer, never an error.
+  - **Deterministic score** = `100 / (1 + severity-weighted findings per record)`
+    (info ×1, warning ×3, critical ×10): 0 findings ⇒ 100; the same findings over
+    fewer clean records score lower. No LLM — stable in CI, comparable run-over-run.
+  - New library exports `computeHealth`, `summarizeHealth`, `healthToMarkdown`
+    and the `HealthEntry` / `HealthRollup` / `HealthRuleDelta` types.
+  - State is profile-scoped and owner-only (0600): `health.jsonl` (append-only)
+    and `snapshots/<planId>.json`, alongside `plans/` under the same secured dir.
+
+## [0.35.0] — 2026-06-19
+
+### Added
+
+- **Progressive-disclosure help.** The front door is now a lifecycle-grouped map
+  (Setup · Detect · Prevent · Remediate · Calls · Govern · Market · Schedule) of
+  ~one line per verb instead of a 194-line wall — bare invoke and `--help` print
+  it. `<verb> --help` gives focused per-command help (summary, synopsis, key
+  options, the verb's lifecycle phase, see-also) rather than the whole surface.
+  New `help [command] [--full]` command; `--full` always escapes to the complete
+  reference. `call`/`market`/`enrich`/`bulk-update`/`schedule` keep their own
+  richer help.
+- **`audit` next-step guidance.** After a human-readable audit, the CLI prints a
+  context-aware next step on stderr (so stdout stays clean for pipes/`--out`):
+  the demo points to `report --demo` and `login`; a saved live audit chains
+  `suggest → plans approve → apply` with the real plan id; a clean snapshot
+  points to `resolve`/`schedule`. Suppressed under `--json`.
+- **`audit --full`** and **`patchPlanToMarkdown(plan, { summary })`** — a summary
+  view (header + Findings-by-Rule table + operation count) for read-side audits.
+
+### Changed
+
+- **`audit` defaults to the summary view** (≈24 lines on the demo vs ≈1,470
+  before); `--full` opts into the per-operation dump. The default stays full for
+  write-preview renders (`bulk-update`, `fix`, `dedupe`, `plans show`, MCP), where
+  you approve specific operations and want every operation's detail. The `--json`
+  machine output is unchanged.
+- **Plan footer reframed** from "This prototype is dry-run only…" to the actual
+  safety invariants ("Dry-run plan — read-only. No provider write happens until
+  you approve specific operations and run `apply`… These safety invariants are
+  not beta."), matching the README and agent skill.
+
+See [docs/dx-punch-list.md](./docs/dx-punch-list.md) for the audit that drove this.
+
 ## [0.34.0] — 2026-06-18
 
 ### Added

package/README.md

@@ -169,6 +169,31 @@ fullstackgtm enrich status --runs                           # last run per sourc
 
 Matching is deterministic: ordered keys, unique hit wins, zero hits falls through to the next key, and multiple hits are never guessed away — they skip (recorded with candidate ids) or flow into the existing `suggest` → `plans approve` chain as `requires_human_record_selection` placeholders. The MVP conflict policy is `never`: enrich only fills blank fields, and `refresh` only re-touches fields its own run-store ledger proves it stamped (per-record/per-field `enrichedAt`, profile-scoped, never written into your portal as custom properties). The `system-only` and `always` rungs of the ladder are phase 2 and are refused explicitly, not silently accepted. Recurring execution belongs to the scheduler — enrich owns no cron logic.
 
+## Acquire: net-new leads, ICP-targeted and dupe-safe by default
+
+`enrich append/refresh` fill blanks on records you already have. **`enrich acquire`** creates *net-new* ones — and routes them through the same dry-run → approve → apply gate, so prospecting can never silently write to your CRM. It discovers people, resolves their work email, scores them against your ICP, dedupes against your CRM, and proposes governed `create_record` operations.
+
+```bash
+fullstackgtm icp interview                                  # emit the ICP question spec; an agent asks it (AskUserQuestion)
+fullstackgtm icp set answers.json --name "RevOps ICP"       # write icp.json (firmographics + persona + fit threshold)
+echo "$PIPE0_API_KEY" | fullstackgtm login pipe0            # discovery + work-email provider, stored 0600
+
+fullstackgtm enrich acquire --provider hubspot              # zero-config: ICP → discover → score → dedup → dry-run diff
+fullstackgtm enrich acquire --provider hubspot --max 25 --save   # cap the batch, persist the needs_approval plan
+fullstackgtm plans approve <id> --operations all
+fullstackgtm apply --plan-id <id> --provider hubspot        # the only step that creates contacts
+```
+
+The **ICP** (`icp.json`) is the single targeting artifact: it generates each provider's discovery filters (Explorium, pipe0/Crustdata) *and* fit-scores every discovered prospect — only above-threshold leads are proposed. Develop one by interview; the CLI can't run `AskUserQuestion` itself, so `icp interview` emits the spec and an agent (Claude Code / Codex) drives it.
+
+**You don't pay to re-discover dupes.** Before the (credit-spending) email step, acquire drops prospects already in your CRM and any seen in a prior run:
+
+- **Pre-email CRM dedup** matches the live snapshot. The LinkedIn URL (`hs_linkedin_url`, read into the snapshot by default — safe everywhere, HubSpot ignores unknown properties) is the strong key; name+domain is the fallback. Created contacts get their LinkedIn URL written back, so coverage — and dedup precision — grows over time. If your CRM has no LinkedIn URLs, acquire says so and recommends populating it.
+- **A cross-run seen cache** remembers everyone already resolved, so re-running the same ICP costs nothing for known people.
+- Two more checkpoints stay precise: the email-level match at plan build, and **resolve-first at apply** (re-checks the live CRM, never double-creates, never charges the meter).
+
+Every run is **metered**: a per-profile budget caps both record count and provider spend (per-day + per-month, whichever binds first), charged only for creates that actually land. `enrich acquire` runs with just an `icp.json` and a `login` — sensible defaults for budget, provider, and create-mapping ship in the box.
+
 ## Schedules: declare a cadence once, keep the governance contract under automation
 
 Everything the CLI produces is accurate the moment it runs and silently stale afterward. The **schedule layer** is the horizontal fix — any read/plan-side command on a cron cadence, one component, every verb (no feature owns its own cron logic):

package/dist/acquireMeter.d.ts

@@ -0,0 +1,67 @@
+/** Budget declared in enrich.config.json under `acquire.budget`. */
+export type AcquireBudget = {
+    records?: {
+        perDay?: number;
+        perMonth?: number;
+    };
+    spend?: {
+        perDay?: number;
+        perMonth?: number;
+        currency?: string;
+    };
+};
+export type AcquireMeterState = {
+    /** UTC day bucket, YYYY-MM-DD. */
+    day: string;
+    /** UTC month bucket, YYYY-MM. */
+    month: string;
+    records: {
+        day: number;
+        month: number;
+    };
+    spendUsd: {
+        day: number;
+        month: number;
+    };
+};
+export type AcquireRemaining = {
+    /** Remaining headroom per window; null = no budget set for that dimension. */
+    records: {
+        day: number | null;
+        month: number | null;
+    };
+    spendUsd: {
+        day: number | null;
+        month: number | null;
+    };
+    /**
+     * The single number that matters: how many MORE records may be created right
+     * now, given every budget dimension and the per-record cost. null = unlimited
+     * (no budget constrains creation). 0 = budget exhausted.
+     */
+    maxRecords: number | null;
+};
+export declare function dayKey(now: Date): string;
+export declare function monthKey(now: Date): string;
+export declare function acquireMeterPath(baseDir?: string): string;
+/**
+ * Roll the window counters forward: a new UTC day zeroes the day buckets, a
+ * new UTC month zeroes the month buckets. Returns a fresh object; never
+ * mutates the input.
+ */
+export declare function rollWindows(state: AcquireMeterState, now: Date): AcquireMeterState;
+/** Load the meter from disk, rolling stale windows forward. Missing = empty. */
+export declare function loadMeter(now: Date, baseDir?: string): AcquireMeterState;
+export declare function saveMeter(state: AcquireMeterState, baseDir?: string): void;
+/**
+ * Compute remaining headroom and the max additional records creatable now.
+ * `costPerRecord` (USD) converts the spend budget into a record ceiling; when
+ * it is 0 the spend budget cannot constrain record count.
+ */
+export declare function remaining(state: AcquireMeterState, budget: AcquireBudget | undefined, costPerRecord: number, now: Date): AcquireRemaining;
+/**
+ * Record a successful batch of creates against the budget and persist.
+ * Returns the updated state. Call AFTER the writes land, so a failed apply
+ * never charges the meter.
+ */
+export declare function recordConsumption(now: Date, recordsCreated: number, spendUsd: number, baseDir?: string): AcquireMeterState;

package/dist/acquireMeter.js

@@ -0,0 +1,145 @@
+/**
+ * The acquire meter — a persistent, windowed budget for net-new lead creation.
+ *
+ * `enrich acquire` proposes `create_record` operations; `apply` writes them.
+ * Both gate on this meter so a profile can never create more leads — or spend
+ * more on enrichment — than its declared budget, per day AND per month
+ * (whichever limit is hit first). The meter is the volume control; a human
+ * still approves the plan (the CLI never auto-writes). State is per-profile,
+ * stored under the credential home so one client's budget never bleeds into
+ * another's.
+ *
+ * Pure where it counts: window math and `remaining()` take an explicit `now`
+ * and operate on a passed-in state, so they are deterministic and testable.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { credentialsDir } from "./credentials.js";
+export function dayKey(now) {
+    return now.toISOString().slice(0, 10);
+}
+export function monthKey(now) {
+    return now.toISOString().slice(0, 7);
+}
+export function acquireMeterPath(baseDir) {
+    return join(baseDir ?? credentialsDir(), "acquire", "meter.json");
+}
+function emptyState(now) {
+    return {
+        day: dayKey(now),
+        month: monthKey(now),
+        records: { day: 0, month: 0 },
+        spendUsd: { day: 0, month: 0 },
+    };
+}
+/**
+ * Roll the window counters forward: a new UTC day zeroes the day buckets, a
+ * new UTC month zeroes the month buckets. Returns a fresh object; never
+ * mutates the input.
+ */
+export function rollWindows(state, now) {
+    const today = dayKey(now);
+    const thisMonth = monthKey(now);
+    return {
+        day: today,
+        month: thisMonth,
+        records: {
+            day: state.day === today ? state.records.day : 0,
+            month: state.month === thisMonth ? state.records.month : 0,
+        },
+        spendUsd: {
+            day: state.day === today ? state.spendUsd.day : 0,
+            month: state.month === thisMonth ? state.spendUsd.month : 0,
+        },
+    };
+}
+/** Load the meter from disk, rolling stale windows forward. Missing = empty. */
+export function loadMeter(now, baseDir) {
+    let raw;
+    try {
+        raw = readFileSync(acquireMeterPath(baseDir), "utf8");
+    }
+    catch {
+        return emptyState(now);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const state = {
+            day: typeof parsed.day === "string" ? parsed.day : dayKey(now),
+            month: typeof parsed.month === "string" ? parsed.month : monthKey(now),
+            records: {
+                day: Number(parsed.records?.day) || 0,
+                month: Number(parsed.records?.month) || 0,
+            },
+            spendUsd: {
+                day: Number(parsed.spendUsd?.day) || 0,
+                month: Number(parsed.spendUsd?.month) || 0,
+            },
+        };
+        return rollWindows(state, now);
+    }
+    catch {
+        return emptyState(now);
+    }
+}
+export function saveMeter(state, baseDir) {
+    const path = acquireMeterPath(baseDir);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+function headroom(limit, used) {
+    if (limit === undefined)
+        return null;
+    return Math.max(0, limit - used);
+}
+/**
+ * Compute remaining headroom and the max additional records creatable now.
+ * `costPerRecord` (USD) converts the spend budget into a record ceiling; when
+ * it is 0 the spend budget cannot constrain record count.
+ */
+export function remaining(state, budget, costPerRecord, now) {
+    const rolled = rollWindows(state, now);
+    const records = {
+        day: headroom(budget?.records?.perDay, rolled.records.day),
+        month: headroom(budget?.records?.perMonth, rolled.records.month),
+    };
+    const spendUsd = {
+        day: headroom(budget?.spend?.perDay, rolled.spendUsd.day),
+        month: headroom(budget?.spend?.perMonth, rolled.spendUsd.month),
+    };
+    const ceilings = [];
+    if (records.day !== null)
+        ceilings.push(records.day);
+    if (records.month !== null)
+        ceilings.push(records.month);
+    if (costPerRecord > 0) {
+        if (spendUsd.day !== null)
+            ceilings.push(Math.floor(spendUsd.day / costPerRecord));
+        if (spendUsd.month !== null)
+            ceilings.push(Math.floor(spendUsd.month / costPerRecord));
+    }
+    const maxRecords = ceilings.length === 0 ? null : Math.max(0, Math.min(...ceilings));
+    return { records, spendUsd, maxRecords };
+}
+/**
+ * Record a successful batch of creates against the budget and persist.
+ * Returns the updated state. Call AFTER the writes land, so a failed apply
+ * never charges the meter.
+ */
+export function recordConsumption(now, recordsCreated, spendUsd, baseDir) {
+    const state = loadMeter(now, baseDir);
+    const next = {
+        day: state.day,
+        month: state.month,
+        records: {
+            day: state.records.day + recordsCreated,
+            month: state.records.month + recordsCreated,
+        },
+        spendUsd: {
+            day: state.spendUsd.day + spendUsd,
+            month: state.spendUsd.month + spendUsd,
+        },
+    };
+    saveMeter(next, baseDir);
+    return next;
+}

package/dist/acquireSeen.d.ts

@@ -0,0 +1,5 @@
+export declare function acquireSeenPath(baseDir?: string): string;
+/** Load the set of seen keys (empty if none/corrupt). */
+export declare function loadSeen(baseDir?: string): Set<string>;
+/** Merge keys into the cache with a `now` timestamp, prune to cap, persist. */
+export declare function recordSeen(keys: string[], now: Date, baseDir?: string): void;

package/dist/acquireSeen.js

@@ -0,0 +1,54 @@
+/**
+ * The acquire "seen" cache — cross-run memory of prospects already processed,
+ * so re-running the same ICP doesn't re-pay the (expensive) email-resolution
+ * step for people we resolved last time. Keyed by stable prospect identity
+ * (LinkedIn URL, name+domain, email); a hit on ANY key means "skip before
+ * paying". Per-profile, stored under the credential home.
+ *
+ * Distinct from the meter (spend budget) and from the live-CRM dedup (the
+ * snapshot match + apply-time resolve-first): this avoids RE-spending across
+ * runs; those avoid double-creating within/against the CRM.
+ *
+ * Zero deps. Stored as { key: lastSeenISO } so the cache can be pruned by age.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { credentialsDir } from "./credentials.js";
+/** Keep the newest N keys; bounds the file for very large/long-running fills. */
+const SEEN_CAP = 50_000;
+export function acquireSeenPath(baseDir) {
+    return join(baseDir ?? credentialsDir(), "acquire", "seen.json");
+}
+/** Load the set of seen keys (empty if none/corrupt). */
+export function loadSeen(baseDir) {
+    try {
+        const store = JSON.parse(readFileSync(acquireSeenPath(baseDir), "utf8"));
+        return new Set(Object.keys(store));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Merge keys into the cache with a `now` timestamp, prune to cap, persist. */
+export function recordSeen(keys, now, baseDir) {
+    if (keys.length === 0)
+        return;
+    let store = {};
+    try {
+        store = JSON.parse(readFileSync(acquireSeenPath(baseDir), "utf8"));
+    }
+    catch {
+        store = {};
+    }
+    const iso = now.toISOString();
+    for (const key of keys)
+        store[key] = iso;
+    let entries = Object.entries(store);
+    if (entries.length > SEEN_CAP) {
+        entries = entries.sort((a, b) => (a[1] < b[1] ? 1 : -1)).slice(0, SEEN_CAP);
+        store = Object.fromEntries(entries);
+    }
+    const path = acquireSeenPath(baseDir);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(store)}\n`, "utf8");
+}