fullstackgtm 0.45.0 → 0.47.0

package/docs/dx-punch-list.md

@@ -1,87 +0,0 @@
-# DX / adoption punch list
-
-Audit date: 2026-06-19. Method: ran the CLI as a new adopter would (bare
-invoke → `doctor` → `audit --demo` → per-command `--help`) and measured the
-friction, rather than reading the source. Companion to the security/strategic
-findings that drove the 0.25.1–0.28.0 hardening releases — same format, same
-intent: a tracked list that drives a release.
-
-## Framing
-
-The **agent path** (SKILL.md verb map, MCP tools, `--json` everywhere,
-gate-shaped exit codes 0/1/2) is cohesive and adopts cleanly. The **human
-path** is the weak side — and the human is a primary user (the consultant-CLI,
-dogfood-on-client-work direction). Every fix below either *deepens an existing
-verb* or *connects two existing verbs*; none adds a new top-level noun. The
-adoption work **is** the "deeper not broader" work.
-
-`doctor` (ends with "Next step") and `fix` (chains audit→suggest→approve→apply)
-already do the right thing. Cohesion here = make every verb behave like
-`doctor` and `fix` already do.
-
-## Findings (evidence-backed)
-
-| # | Finding | Evidence | Impact |
-| --- | --- | --- | --- |
-| F1 | **Front door is a firehose** | bare invoke = 194 lines; 22 verbs / 87 distinct flags; `cli.ts` is 3,615 lines | New user can't find the ~6 things they actually do |
-| F2 | **Credential-free entry point dead-ends** | `audit --demo` (the README's "try it first") dumps **1,467 lines** to stdout and ends on a blank line — no "next step," unlike `doctor` | The single most-run first command strands you |
-| F3 | **No per-command help** | `dedupe --help`, `audit --help` fall through to the same 194-line global wall | A stuck user gets the firehose, not the answer |
-| F4 | **No altitude control on reads** | `audit` has only `--json` / `--out` / `--format`; no `--summary` / `--top` / `--quiet`. Human mode *is* the 1,467-line dump | Default human output is unreadable yet not machine-parseable |
-| F5 | **Tone undercuts positioning** | `audit --demo` footer: "This prototype is dry-run only" | Reads as toy vs. the beta/production-safety-invariant framing |
-| F6 | **No guided mode** | `readline` is used only for the login secret prompt | Every workflow is hand-assembled from flags; nothing scaffolds the loop |
-
-## Fix sequence (highest leverage first)
-
-### 1. Progressive-disclosure help — IN PROGRESS
-Fixes **F1, F3**. The full `usage()` becomes the explicit full reference
-(`fullstackgtm help --full`). Add:
-- `shortUsage()` — a ~30-line map of the verbs grouped by lifecycle phase
-  (Setup · Detect · Prevent · Remediate · Calls · Govern · Market · Schedule),
-  one line each, ending with `<command> --help` and `help --full` pointers.
-  Becomes the default for bare invoke and `--help`.
-- `commandHelp(command)` — focused per-verb help (summary, synopsis, where it
-  sits in the loop, key options, see-also). `<verb> --help` zooms in instead
-  of dumping the surface. `call`/`market`/`enrich`/`bulk-update`/`schedule`
-  keep their existing bespoke help.
-- `help [command] [--full]` command.
-
-### 2. Every verb hands you the next step — DONE (audit keystone)
-Fixes **F2**. `auditNextStep()` gives `audit` context-aware forward guidance on
-stderr (stdout stays clean for pipes/`--out`; suppressed under `--json`):
-- **demo/sample** → "Client-ready writeup: `report --demo`" + "Run on your CRM:
-  `login hubspot` → `audit --provider hubspot --save`"
-- **live + `--save`** → the governed spine: `suggest` → `plans approve
-  --values-from` → `apply`, with the real plan id
-- **0 findings** → "clean — gate new records with `resolve`, schedule a check"
-
-The lifecycle spine made *experiential* — each command knows its phase and
-points forward (`doctor`/`fix` were the templates). `audit` is the keystone
-(the documented dead-end); the helper pattern now generalizes to the other read
-verbs (`report`, `resolve`, `dedupe` previews) in a follow-up.
-
-### 3. Altitude control on the firehose — DONE
-Fixes **F4**. `patchPlanToMarkdown(plan, { summary })` gains a summary view
-(header + Findings-by-Rule table + operation count + pointers to `--full` and
-`report`). `audit` defaults to it — **1,467 → 24 lines** on the demo — with
-`--full` to opt back into the per-operation dump. The default stays *full* for
-every other caller (bulk-update, fix, dedupe, plans show, MCP): write-preview
-verbs keep full operation detail because you approve specific ops there. The
-principled split — audit = "what's wrong" (summary → `report`); write verbs =
-"exactly what I'll change" (full) — is the real win.
-
-### 4. Tone pass — DONE
-Fixes **F5**. The "This prototype is dry-run only" footer is replaced
-everywhere with safety-invariant framing matching README/SKILL: "Dry-run plan —
-read-only. No provider write happens until you approve specific operations and
-run `apply`; placeholder values are refused without an explicit override. These
-safety invariants are not beta." No "prototype" string remains in user output.
-
-## Deferred (bigger bets, gated on 1–4 landing)
-- **Engagement workspace**: per-client `.fullstackgtm/` state that accumulates
-  snapshots, plans, evidence, and a health-over-time score — turns episodic
-  audits into a continuously-operated system.
-- **Journey commands**: 2–3 opinionated composites (onboard-a-client,
-  health-rollup) sequencing existing verbs into revops jobs.
-
-There is no point building the engagement workspace while the front door dumps
-1,467 lines. Land the DX fixes first.

package/docs/roadmap-to-1.0.md

@@ -1,211 +0,0 @@
-# fullstackgtm: 0.1 → 1.0
-
-The planned, versioned path from first publish to a stable 1.0. Each milestone
-is shippable on its own, ordered so that every step consolidates the
-architecture before the next step expands it. The invariants that hold at
-every version:
-
-1. **The package is the product; the app is an adapter.** Anything the app
-   needs from a provider goes through the package connector. New capability
-   lands in the package first.
-2. **Reads are free, writes are patch plans.** No code path may mutate a
-   provider except `applyPatchPlan` / `applyOperation` with explicit approval.
-3. **Deterministic and diffable.** Same inputs produce the same findings with
-   the same ids. Golden tests over the demo dataset enforce this.
-4. **Zero-dependency core.** Connectors use `fetch`; optional integrations
-   (MCP) stay optional peers.
-
-## 0.1.0 — The loop exists (done)
-
-Canonical model, pluggable rule engine, patch plans, safe apply, HubSpot
-connector, CLI/MCP, demo dataset, CLI auth (private app token, loopback
-OAuth), broker pairing against a hosted deployment, CI + tag-publish
-automation.
-
-## 0.2.0 — Provider parity and operational trust (done)
-
-- **Salesforce connector** behind the same `GtmConnector` contract: SOQL with
-  cursor pagination, PATCH write-back, probabilities normalized to canonical
-  0..1, never drops unresolvable records.
-- **Salesforce CLI auth**: native device flow (code on any device, no client
-  secret, silent refresh) plus manual token + instance URL.
-- **Broker mint for Salesforce**: paired CLIs receive `accessToken +
-  instanceUrl + fieldMappings` from the org's stored credentials.
-- **CLI token observability**: paired-CLI list with last-used timestamps and
-  one-click revoke in the dashboard.
-- App consolidation: `convex/salesforceActions.ts` collapses onto the package
-  connector like the HubSpot path did.
-
-## 0.3.0 — One patch-plan vocabulary (done)
-
-The last internal duplication: the app's durable `patchPlans` tables speak
-`verb`/`operation` strings while the package speaks typed `PatchOperation`s.
-
-- Package: add a `PlanStore` interface (persist plan → approve operations →
-  record runs) so durable workflows are a first-class framework concern, not
-  an app concern.
-- App: migrate `patchPlans`/`patchOperations` rows to the package types
-  (schema migration with a compatibility window), route
-  `patchPlanActions.apply` through `applyPatchPlan`.
-- Exit criterion: the dashboard review queue and `fullstackgtm apply` operate
-  on byte-identical plan documents.
-
-## 0.4.0 — Policy as config, rules as packages (done)
-
-Make the rule engine the community surface.
-
-- `fullstackgtm.config.json` (or `.ts`): policy thresholds, enabled rules,
-  per-rule severity overrides, custom rule module paths.
-- Rule metadata: category, default severity, docs URL; `fullstackgtm rules`
-  becomes generated documentation.
-- 10–15 additional built-in rules drawn from real RevOps pain: duplicate
-  accounts by domain, contacts without owners, deals closing this quarter
-  with no activity in 14 days, stage/probability drift, currency mismatches.
-- Exit criterion: a third party can publish an npm package of rules and a
-  user can enable it from config without forking.
-
-## 0.5.0 — Time: snapshot history and drift (done)
-
-- Snapshot archive conventions (local directory or any mounted/S3-backed
-  path) with `fullstackgtm snapshot --archive`.
-- `fullstackgtm diff <a> <b>`: what changed between snapshots — records,
-  fields, and *findings* (hygiene drift), built on the stable-id property.
-- Audit trends in the hosted app (the observability layer earns its keep).
-- Exit criterion: a nightly CI job can fail on hygiene regression, not just
-  hygiene presence.
-
-## 0.6.0 — Many systems, one entity (done — Stripe is the first non-CRM connector)
-
-The original thesis: GTM data disagrees across systems.
-
-- Entity resolution over `identities` claims: merge canonical records from
-  multiple snapshots (CRM + marketing + billing) by domain/email/external-id
-  heuristics, with explicit confidence and human-reviewable merge plans (the
-  patch-plan safety model applied to identity).
-- Cross-system audit rules: "account exists in billing but not CRM",
-  "marketing-qualified contact has no CRM owner".
-- First non-CRM connector (likely billing — Stripe — or marketing) to prove
-  the contract generalizes.
-- Exit criterion: one audit over a merged snapshot from two live systems.
-
-## 0.7.0 — Sync maturity (done)
-
-- Incremental fetch: provider cursors (HubSpot `updatedAfter` search,
-  Salesforce `SystemModstamp` filters) behind an optional
-  `fetchChanges(since)` connector capability.
-- Conflict surfacing: when a provider value changed under an unapplied patch
-  operation, the plan flags it instead of writing blind (compare-and-set).
-- Exit criterion: hourly sync of a 100k-record org without full re-pulls.
-
-## 0.8–0.9 — Hardening and freeze (done)
-
-- API review and freeze of `types.ts`, connector contract, CLI flags, MCP
-  schemas; deprecations resolved.
-- Security review of the auth surfaces (credential store, broker endpoints,
-  token lifecycle); rate limiting on the device-flow endpoints.
-- Docs site with the operating-model registry as browsable reference.
-- Performance pass: streaming snapshots for very large orgs.
-
-## 0.10 → 0.28 — the layers, as shipped
-
-The plan above ended at the freeze; what shipped next grew the surface
-outward, one layer per release, each consolidating before the next expanded:
-
-- **0.11** — the suggest chain: deterministic placeholder values with
-  confidence + reasons, `plans approve --values-from`.
-- **0.12** — governed merge: `merge_records` (HubSpot contacts / companies /
-  deals), survivor suggestions capped at low confidence.
-- **0.13–0.14** — call intelligence: `call parse|score|link|plan`, LLM
-  extraction behind the bring-your-own-key seam, deterministic baseline,
-  provenance-marked insights.
-- **0.15** — the Prevent layer: the `resolve` create gate plus record-source
-  provenance and attribution.
-- **0.16–0.22** — the market map: content-addressed captures, classification
-  with mechanical span verification, front states and drift, axis discovery,
-  overlay directives, scale estimation, the field report.
-- **0.19 / 0.23** — governed write verbs (`bulk-update`, then `dedupe`,
-  `reassign`, `fix`) and the enrich layer (Apollo / Clay, fill-blanks-only
-  plans).
-- **0.24** — the schedule layer: horizontal cron, read/plan-side allowlist,
-  scheduling never auto-approves.
-- **0.25** — agent skill distribution (`npx skills add fullstackgtm/core`).
-- **0.25.2–0.26** — the security-hardening train: write-path integrity
-  (HMAC-signed approvals re-verified at apply; archive-of-duplicate and
-  irreversible-op drift guards; recovery snapshots) plus crontab/SSRF/XSS/
-  error-body/CSV/credential-mode fixes, each verified by adversarial re-attack.
-- **0.27** — trust & transparency: `audit-log export|verify` (hash-chained,
-  signed apply-run record), SECURITY.md + DATA-FLOWS.md + company-of-record,
-  call-transcript insight grounding.
-- **0.28** — connectors, credentials & supply chain: opt-in OS keychain,
-  broker-https enforcement, the build/CI dist-integrity gate (published dist is
-  provably from source), Salesforce-merge capability matrix.
-
-## 0.29 → 0.43 — from hygiene to the full outbound loop, as shipped
-
-The next train extended the governed spine from *fixing the CRM* to *filling
-it and acting on it*, without ever loosening the write gate:
-
-- **0.29–0.34** — market-map maturation (config suggestion + taxonomy types,
-  sourcing helpers, competitor discovery, vendor logos/scale in the report)
-  plus call-type classification with type-specific coaching rubrics (0.32);
-  Salesforce `dedupe`/`merge_records` via SOAP and pipeline-aware closed/won
-  detection (0.30).
-- **0.35–0.36** — DX cohesion: progressive-disclosure help, summary-first
-  `audit` with next-step guidance; the engagement workspace — a deterministic
-  `health` verb over a per-profile timeline.
-- **0.37–0.39** — acquire: `enrich acquire` (net-new, ICP-targeted,
-  resolve-first deduped, metered lead creation), lead assignment policies so
-  leads are never born ownerless, the LinkedIn (HeyReach) discovery source
-  with email resolution, and run observability for broker-paired CLIs.
-- **0.40** — Salesforce reaches full write parity with HubSpot
-  (`create_record`); HubSpot date-field writes no longer false-conflict.
-- **0.41** — signal-based outbound: `signals fetch/list/outcome/weights`,
-  `icp judge`/`icp eval` (timing × fit × memory, golden-set calibration
-  gate), `draft` (trigger-grounded openers as governed plans), and the LLM
-  base-URL override.
-- **0.42** — bulk apply for lead creation (HubSpot batch + Salesforce
-  composite).
-- **0.43** — the on-ramp and the seams: `init` workspace scaffolding,
-  `docs/recipes.md` (five composable plays), and the contact/account seam
-  campaign — contact-granular outbound end to end, account-level acquire for
-  ABM, `health` by object type.
-
-The known-gaps list below predates these layers and has been re-verified
-against the 0.43 surface (2026-07): still accurate, still open.
-
-## Known real-portal gaps to close before 1.0
-
-Found by exercising the published package as a fresh RevOps user with a real
-CRM (2026-06):
-
-- **Rate-limit resilience.** No 429/retry/backoff handling anywhere; a
-  mid-size portal snapshot is ~1,000+ sequential page requests and one
-  transient failure aborts the run. Fix: honor `Retry-After`, retry
-  idempotent reads with backoff.
-- **`fetchChanges` 10k truncation.** The HubSpot search API caps at 10,000
-  results; the connector stops silently at MAX_PAGES. Fix: detect the cap
-  and fall back to (or instruct) a full snapshot, loudly.
-- **MCP plan hand-off.** `fullstackgtm_audit` can only return the full plan
-  inline (200KB+ on real data) while `fullstackgtm_apply` requires a file
-  path. Fix: an `outPath` option on the audit tool plus a summary-only
-  output mode.
-- **Scope-complete login validation.** `login hubspot` validates against the
-  owners endpoint only, so an under-scoped token passes login and fails
-  mid-audit. Fix: probe each required object endpoint at login and report
-  missing scopes up front.
-
-## 1.0.0 — The contract (not yet declared)
-
-Semver stability commitment on the canonical model, rule interface, connector
-contract, plan format, CLI, and MCP tools. Declared only after the API
-surface has survived external usage and the real-portal gaps above are
-closed. From there, new providers and new rules are minor releases; the
-model only breaks at 2.0.
-
-## Deliberately out of scope until after 1.0
-
-- Hosted multi-org analytics across customers
-- Non-deterministic (LLM-scored) rules — they can *propose*, but the
-  deterministic engine stays the system of record for findings
-- Workflow orchestration (sequences, cadences) — adjacent product, not
-  framework