fullstackgtm 0.43.0 → 0.45.0

package/llms.txt

@@ -20,6 +20,7 @@ at/above `--fail-on`.
 - [Contributing](https://github.com/fullstackgtm/core/blob/main/CONTRIBUTING.md): dev setup, the open-core mirror model, the release ritual
 - [API reference](https://github.com/fullstackgtm/core/blob/main/docs/api.md): semver-covered surfaces — canonical model, rule interface, plan/apply contract, connector contract, config, CLI, MCP tools
 - [CRM-health lifecycle](https://github.com/fullstackgtm/core/blob/main/docs/crm-health-lifecycle.md): the Prevent → Detect → Remediate → Verify/Attribute model; no-new-dupes design
+- [TAM mapping](https://github.com/fullstackgtm/core/blob/main/docs/tam.md): size the reachable market from the ICP, then populate it with scheduled governed acquire and track coverage to an ETA
 - [CHANGELOG](https://github.com/fullstackgtm/core/blob/main/CHANGELOG.md): release history
 
 `fullstackgtm resolve <type>` is the create gate: exit 0 = safe to create,
@@ -58,6 +59,60 @@ uncertainty; report bubbles ∝ estimated share only when signals exist.
 Storage is profile-scoped under `<home>/market/<category>`. MCP:
 `fullstackgtm_market_worksheet`, `fullstackgtm_market_observe`.
 
+## Key invariants (TAM mapping)
+
+`fullstackgtm tam` sizes the reachable market FROM the ICP and then iteratively
+fills it — not a one-shot headline. `tam estimate` computes a transparent model:
+account universe × ACV = TAM (account/per-logo basis by default; `--acv-basis
+buyer` for per-seat = contacts × ACV), where contacts = accounts ×
+buyers/account is the population target. The account count is `--accounts <n>`
+(assumption), OR `--source theirstack` — the TECHNOGRAPHIC universe: counts
+companies that USE a CRM/MAP (`firmographics.technologies` → TheirStack
+`company_technology_slug_or`) + geo + employee bounds; the real RevOps buying signal
+AND the only source that returns a LIST (`tam accounts --source theirstack` pulls
+real companies name/domain, `--out csv`/`--json`, `--max` caps credit spend; a
+count is cheap but NOT free — limit:0 is rejected so a count returns 1 row ≈ 3
+credits, a list pull ≈ 3/company; `login theirstack`). OR `--source explorium` — a firmographic
+count via `/v1/businesses` (`total_results`), a count ONLY (Explorium 403s on
+list-pull, can't target by CRM-usage; must OMIT `size` or it caps the total; capped
+at 60,000 `EXPLORIUM_BUSINESS_COUNT_CAP` → `provider:explorium (≥60k cap — floor)` +
+⚠). Verified live: people endpoints can't size a market (Explorium `/v1/prospects`
+total == page size; pipe0/Crustdata returns only a cursor — `--source pipe0` for
+estimate is REJECTED, it's a population source). The model always LABELS
+`accountsSource` (provider:theirstack/explorium vs assumption). ACV must be a
+real ANNUAL figure the operator CONFIRMS — `--acv <annual-usd>`, OR `--acv-from-crm
+--deal-period monthly|quarterly|annual` which takes the median closed-won amount and
+ANNUALIZES it (the period is required — a deal can be MRR/quarterly/annual and
+guessing is a 4–12× error; $15k/mo → $180k). NO band defaults, and a bare
+`--provider` does NOT auto-set ACV (HubSpot is the COVERAGE source, not the ACV) —
+`estimate` REFUSES without a confirmed ACV. Buyers/account is `--buyers-per-account`
+OR the CRM's avg-contacts-per-account OR a labeled `assumption:1-buyer`. Both
+`acv.source` and `universe.buyersSource` are labeled (incl. deal count + the
+period×factor, so a thin signal like "1 deal" is visible). Optional
+citable cross-checks (`{claim,valueUsd?,sourceUrl,quote}`) sit beside the
+bottom-up number as a top-down sanity check. `estimate`
+records a coverage BASELINE (CRM counts now) so `status` attributes what the
+campaign added. `tam populate --cron` schedules `enrich acquire --source <s>
+--save` — the ONE create-side verb the schedule allowlist permits, and only in
+its plan-producing `--save` form: each firing queues a needs_approval lead plan,
+the acquire meter is charged only at apply, and apply stays `apply --plan-id`
+(re-checked approved). `tam status` measures coverage on the INTERSECTION of CRM ×
+TAM-ICP, not a raw count: `tam estimate` stores the ICP filter (`model.targeting`),
+and status CLASSIFIES each domain-bearing account into in-TAM / out-of-TAM / unknown
+(checked on size+industry — geo + "uses-CRM" aren't on a CanonicalAccount, so a
+`--reverify` re-enrich is future; the classifier labels what it checked). ONLY
+in-TAM counts toward coverage, so off-ICP accounts loaded from elsewhere can't
+inflate it. Bottom-up vs top-down reconciliation: the in-TAM count is a FLOOR on the
+real universe (those are verified members), so when in-TAM ≥ the estimate, status
+stops reporting a fake 100% and flips to "estimate was a floor — real market is at
+least N (`reconciledUniverse = max(estimate, inTam)`); re-estimate for the headroom".
+`--save` stamps an append-only timeline. `tam report` (markdown) and `status` project
+an ETA on the IN-TAM accounts/day burn across the timeline → days-remaining → fill
+date — and REFUSE to project (honest "not enough history") below two readings, a flat
+rate, or zero elapsed time.
+Coverage + ETA are deterministic (no LLM, byte-stable). Storage profile-scoped
+under `<home>/tam/<name>/` (`model.json` + `coverage.jsonl`, 0600).
+
 ## Key invariants (governed write verbs)
 
 `bulk-update <object> --where … (--set|--archive|--create-task)` filters the
@@ -123,8 +178,12 @@ and no webhook ingestion (Phase 2). Never auto-writes.
 The timing/outbound layer turns "who changed" into one grounded, governed
 opener — and **never sends**. `signals fetch` captures fresh buying triggers
 into a profile-scoped ledger (free Greenhouse/Lever/Ashby ATS scrapers in the
-box; funding/social via `ingest`/`--from`), keyed by **account domain**, ranked
-by learned `weights`; it writes NOTHING to the CRM. `icp interview|set|show`
+box; funding/social via `--from`; connected platforms via `--connector`
+file/serpapi-news/hubspot-forms with secrets through the credential ladder; and
+push platforms via the webhook spool — `--connector file` reads the conventional
+landing zone `<home>/signals/spool/*.jsonl`, see docs/signal-spool-format.md),
+keyed by **account domain**, ranked by learned `weights`; it writes NOTHING to
+the CRM. `icp interview|set|show`
 builds `icp.json`; `icp judge` ranks fresh signals into send/nurture/skip — pass
 a snapshot (`--provider`/`--input`/`--demo`) and each decision resolves its CRM
 target: `accountId`, the best `contact {id,email,title}`, and `contacts[]` (all
@@ -135,8 +194,11 @@ bar). `draft` emits ONE trigger-grounded opener per hot account as a governed
 `create_task` targeting the resolved `contact.id` (or `accountId`) — a
 domain-only decision (account not yet in the CRM) is REJECTED with "acquire it
 first" (run `enrich acquire`, re-judge with the snapshot). `--channel
-email|linkedin|task` shapes the opener; it is a task the operator sends from
-their own tool, never an automated send. `signals outcome --account <domain>
+email|linkedin|task` shapes the opener. After `plans approve`, applying the draft
+plan logs the touch as a CRM task (`apply --provider <crm>`) OR renders it to the
+governed outbox (`apply --channel outbox` → `<home>/signals/outbox/<channel>.jsonl`
+for a downstream sender to drain). Either way the CLI **transmits nothing** — the
+outbox is the send-side mirror of the spool; the always-on sender is hosted/opt-in. `signals outcome --account <domain>
 --contact <id> --result replied|...` credits the contact reached so weights
 re-learn. The contact↔account join (`contact.accountId` + `account.domain`) is
 surfaced at every hop, so the loop is contact-coherent end to end — see the
@@ -147,18 +209,28 @@ surfaced at every hop, so the loop is contact-coherent end to end — see the
 `fullstackgtm schedule` is the horizontal scheduler — no feature namespace
 owns cron logic. `add "<command>" --cron "<expr>"` validates the command
 against the read/plan-side allowlist (audit, snapshot, enrich append|refresh,
-market capture|refresh, suggest, report, doctor) and the 5-field cron
-expression, but touches no crontab; `install` materializes enabled entries
-into a sentinel-delimited managed block (`# >>> fullstackgtm <profile> >>>`)
-replaced wholesale on re-install, lines outside it untouched; `uninstall`
-removes only the block. Scheduling never auto-approves: `apply` is
+enrich acquire --save, market capture|refresh, signals fetch, icp judge|eval,
+draft, suggest, report, doctor) and the 5-field cron
+expression, but touches no system timer; `install` materializes enabled
+entries into the platform timer (`--timer` defaults launchd on macOS,
+crontab elsewhere). crontab: a sentinel-delimited managed block
+(`# >>> fullstackgtm <profile> >>>`) replaced wholesale on re-install, lines
+outside it untouched. launchd: one LaunchAgent plist per entry
+(`com.fullstackgtm.<profile>.<id>` in `~/Library/LaunchAgents`), the fleet
+replaced wholesale, foreign plists untouched — chosen because macOS gates
+`crontab` writes behind Full Disk Access (unpromptable TCC), while
+LaunchAgents need no permission and coalesce firings missed during sleep
+into one run on wake. `uninstall` removes only what install created.
+Scheduling never auto-approves: `apply` is
 schedulable ONLY as `apply --plan-id <id>` and every firing re-checks the
 plan is approved — unapproved plans record a `plan_not_approved` no-op run,
 no flag relaxes this. `schedule run <id>` is the single provider entry point
-(in-process dispatch, never shell); run records (exit code, output tail,
+(in-process dispatch, never shell; a second cron trigger in the same minute
+records a `duplicate_firing` no-op — launchd double-triggers the Vixie
+dom+dow OR corner); run records (exit code, output tail,
 artifacts: plan ids / enrich run labels, trigger cron|manual) land under
 `<home>/schedule/runs/<id>/`. `status` shows next firing and surfaces missed
-firings (visibility only — local cron has no catch-up). Providers beyond
+firings (visibility only — cron has no catch-up). Providers beyond
 `local` are not yet implemented (future: codegen scaffolds, same contract).
 
 ## Key invariants (engagement workspace / health)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.43.0",
+  "version": "0.45.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

@@ -63,10 +63,11 @@ credentials AND stored plans per client org.
 | `call parse\|score\|link\|plan` | Transcripts → evidence-quoted insights, rubric scorecards, deal linking, governed next-step writes |
 | `enrich append\|refresh\|ingest\|status` | Governed enrichment (Apollo pull / Clay ingest), fill-blanks-only plans |
 | `enrich acquire [--source explorium\|pipe0\|linkedin]` | Net-new ICP-targeted lead gen: resolve-first deduped `create_record` plans, capped by a per-profile windowed meter (records + spend); owner-stamped via `acquire.assign`/`--assign-owner` (never born ownerless); links each lead to a domain-stamped, signal-watchable account; `acquire.create.company` acquires accounts (ABM); `--source linkedin --list <id>` reads a HeyReach lead list (Phase 1 discovery, read-only — never sends); never auto-writes |
-| `signals fetch\|list\|outcome\|weights` | Detect-side timing layer: capture fresh buying triggers into a profile-scoped ledger (free Greenhouse/Lever/Ashby ATS in the box; funding/social via ingest), ranked by learned weights. Writes NOTHING to the CRM; `outcome --account <domain> --contact <id> --result …` re-weights which triggers earn a touch |
+| `signals fetch\|list\|outcome\|weights` | Detect-side timing layer: capture fresh buying triggers into a profile-scoped ledger (free Greenhouse/Lever/Ashby ATS in the box; `--from` staged files; `--connector file\|serpapi-news\|hubspot-forms` to pull connected platforms / read the webhook spool `<home>/signals/spool`, secrets via the credential ladder), ranked by learned weights. Writes NOTHING to the CRM; `outcome --account <domain> --contact <id> --result …` re-weights which triggers earn a touch |
 | `icp interview\|set\|show\|judge\|eval` | Build the ICP, then `judge` ranks fresh signals into send/nurture/skip — pass a snapshot (`--provider`/`--input`) and each decision resolves its CRM target (`accountId` + the `contact`/`contacts` to reach). `eval` is the calibration gate (exit 2 below the bar) |
-| `draft [--from-judge latest] [--channel email\|linkedin\|task]` | One trigger-grounded opener per hot account → a governed `create_task` targeting the resolved `contact.id` (or `accountId`); rejects a domain-only decision ("acquire it first"). **Never sends** — the opener is a task the operator sends from their own tool |
+| `draft [--from-judge latest] [--channel email\|linkedin\|task]` | One trigger-grounded opener per hot account → a governed `create_task` targeting the resolved `contact.id` (or `accountId`); rejects a domain-only decision ("acquire it first"). **Never sends** — after `plans approve`, `apply --provider <crm>` logs it as a CRM task, or `apply --channel outbox` renders it to `<home>/signals/outbox/<channel>.jsonl` for a downstream sender to drain; the CLI transmits nothing |
 | `market init\|capture\|classify\|worksheet\|observe\|fronts\|axes\|overlay\|scale\|report\|refresh` | Competitive category map; evidence quotes verified verbatim against stored captures |
+| `tam estimate\|accounts\|status\|report\|populate` | Size the reachable market FROM the ICP (real account count × real ACV; buyers/account → contact target), then iteratively fill it: `populate` schedules plan-only `enrich acquire --save` (apply stays gated), `status` classifies CRM accounts vs the TAM ICP into **in-TAM / out-of-TAM / unknown** (only in-TAM counts — junk loaded from elsewhere doesn't inflate coverage; checked on size+industry, geo/tech need re-enrich) and flips to "estimate was a FLOOR, revise up" when bottom-up in-CRM exceeds the top-down estimate; `--save` stamps a timeline, `report` projects burn-up + ETA on the in-TAM rate. **`estimate --source theirstack`** counts companies that USE a CRM/MAP (`firmographics.technologies`) — the real RevOps universe — and **`tam accounts --source theirstack`** pulls the actual company LIST (names+domains, `--out csv`) at ~3 credits/company — `--dry-run [--usd-per-credit <r>]` prices the pull + full TAM for 0 credits, `--confirm` gates pulls above `--max-credits` (default 150). `--source explorium` = firmographic count only (no list, 60k cap = floor); else `--accounts`. **ACV must be a real ANNUAL figure you confirm** — `--acv <annual-usd>`, or `--acv-from-crm --deal-period monthly\|quarterly\|annual` (median closed-won, annualized); NO band defaults, a bare `--provider` does NOT set ACV (HubSpot=coverage), refuses without one. Buyers/account = CRM avg-contacts or explicit. Every number labeled with its source |
 | `schedule add\|list\|remove\|enable\|disable\|run\|install\|uninstall\|status` | Horizontal cron; read/plan-side allowlist only — scheduling NEVER auto-approves |
 | `report` | Client-ready audit deliverable (markdown or self-contained HTML) |
 | `health [--json]` | Per-profile CRM health timeline: deterministic 0–100 score, trend, per-rule deltas — accrues from `audit --save`, read-only |
@@ -78,7 +79,7 @@ Add `--json` for machine-readable output on any command.
 ## MCP server (alternative surface, same gates)
 
 ```bash
-npx -y -p fullstackgtm -p @modelcontextprotocol/sdk -p zod fullstackgtm-mcp
+npx -y fullstackgtm-mcp
 ```
 
 Tools over stdio: `fullstackgtm_audit` (read-only), `fullstackgtm_rules`,

package/src/audit.ts

@@ -18,6 +18,19 @@ const DEFAULT_POLICY: Omit<GtmPolicy, "today"> = {
   requireAccountForDeal: true,
 };
 
+/**
+ * Wall clock for the plan's stdout-bound `createdAt`, honoring the
+ * SOURCE_DATE_EPOCH reproducible-build convention (seconds since the Unix
+ * epoch). When set, `audit --demo --json` is byte-deterministic across
+ * re-runs — golden tests and CI diffs can pin the payload. Unset (normal
+ * use) it is the real clock, exactly as before.
+ */
+function nowIso(): string {
+  const epoch = process.env.SOURCE_DATE_EPOCH;
+  if (epoch && /^\d+$/.test(epoch)) return new Date(Number(epoch) * 1000).toISOString();
+  return new Date().toISOString();
+}
+
 export function defaultPolicy(today = new Date().toISOString().slice(0, 10)): GtmPolicy {
   return {
     ...DEFAULT_POLICY,
@@ -28,20 +41,33 @@ export function defaultPolicy(today = new Date().toISOString().slice(0, 10)): Gt
 /**
  * Run every rule over the snapshot and collect the results into a single
  * dry-run patch plan. Pass custom rules to extend or replace the built-ins.
+ * `onRule` reports per-rule progress (presentation only — a throwing callback
+ * never fails the audit).
  */
 export function auditSnapshot(
   snapshot: CanonicalGtmSnapshot,
   policy: GtmPolicy = defaultPolicy(),
   rules: GtmAuditRule[] = builtinAuditRules,
+  onRule?: (ruleId: string, phase: "start" | "done", findings?: number) => void,
 ): PatchPlan {
   const context = { snapshot, policy, index: buildSnapshotIndex(snapshot) };
   const findings: AuditFinding[] = [];
   const operations: PatchOperation[] = [];
 
   for (const rule of rules) {
+    try {
+      onRule?.(rule.id, "start");
+    } catch {
+      // progress is presentation-only
+    }
     const result = rule.evaluate(context);
     findings.push(...result.findings);
     operations.push(...result.operations);
+    try {
+      onRule?.(rule.id, "done", result.findings.length);
+    } catch {
+      // progress is presentation-only
+    }
   }
 
 
@@ -52,7 +78,7 @@ export function auditSnapshot(
   return {
     id: `patch_plan_${stableHash(`${snapshot.provider}:${snapshot.generatedAt}:${findings.length}:${operations.length}`)}`,
     title: "GTM hygiene audit patch plan",
-    createdAt: new Date().toISOString(),
+    createdAt: nowIso(),
     status: operations.length > 0 ? "needs_approval" : "draft",
     dryRun: true,
     summary: `${findings.length} findings and ${operations.length} proposed dry-run operations.`,