fullstackgtm 0.28.1 → 0.28.3

package/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.28.3] — 2026-06-16
+
+Fix broken links in the published mirror. CONTRIBUTING.md and CLAUDE.md
+referenced `../../docs/open-core-boundary.md` — a monorepo-root path that
+escapes the repo on the mirror (where the package is the repo root) and targets
+a doc the mirror doesn't carry. Made those references self-contained (the
+open-core model and release ritual are explained inline). A full sweep confirms
+every relative link in the shipped docs now resolves within the package/mirror.
+
+## [0.28.2] — 2026-06-16
+
+Collaborator/co-maintainer onboarding (from a readiness review). No runtime
+code changes; one dev-ergonomics fix.
+
+### Fixed
+
+- **Package-local `npm test` no longer silently passes with zero tests.** A
+  `pretest` guard fails with a pointer to run package tests from the monorepo
+  root (the tests live there; the package-local script is meaningful only on the
+  published mirror). Previously a maintainer could change code, run the package's
+  test command, see green, and ship a regression.
+
+### Added
+
+- **CONTRIBUTING.md at the package root** (the README link previously 404'd in
+  the source repo — it existed only in the mirror-staging dir). Covers dev setup,
+  the test-from-root rule, the open-core mirror topology, the release ritual, and
+  the access a co-maintainer needs to cut a release.
+- **docs/architecture.md** — module map + snapshot → audit → plan → apply data
+  flow + "where do I add a rule / connector / operation".
+- A package-scoped **CLAUDE.md** so an agent/maintainer isn't pointed at the
+  hosted app's Convex stack.
+
+### Changed
+
+- README benchmark line reconciled with RESULTS.md (1,088-run, six models);
+  roadmap-to-1.0 shipped-layers list extended through 0.28.
+
 ## [0.28.1] — 2026-06-16
 
 Company-of-record correction: the legal entity is **Full Stack GTM LLC** and the

package/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+Thanks for your interest in `fullstackgtm`! This covers both outside
+contributors and co-maintainers.
+
+## How this repository works (open-core mirror)
+
+`fullstackgtm` is open-core. The development **source of truth** is a private
+monorepo (the package lives at `packages/fullstackgtm`), alongside the hosted
+Full Stack GTM LLC application. `scripts/sync-oss.sh` publishes a **one-way
+mirror** to [github.com/fullstackgtm/core](https://github.com/fullstackgtm/core)
+and to npm. The mirror has the package at its repo root, the tests in `tests/`
+with rewritten import paths, and `dist/` committed (so `npm install
+github:fullstackgtm/core` works without a build step).
+
+- **Issues / PRs:** open them on the public mirror (`fullstackgtm/core`). A
+  maintainer applies accepted changes in the monorepo with credit
+  (`Co-authored-by`); they land in the next mirrored release.
+- The open/closed boundary: client tools, the canonical model, rules, the
+  plan/apply contract, connectors, CLI, and MCP server are open; the hosted Full
+  Stack GTM application's server code is not. **Features never move from open to
+  closed**, and new work here must run standalone (no hosted deployment
+  required). (Maintainers: the full boundary policy lives in
+  `docs/open-core-boundary.md` in the development monorepo.)
+
+## Architecture
+
+Start with [docs/architecture.md](./docs/architecture.md) for the module map and
+the snapshot → audit → plan → approve → apply data flow, then
+[docs/api.md](./docs/api.md) for the 1.0 contract surface (canonical model, rule
+interface, connector interface, governed write verbs, MCP tools).
+
+## Development
+
+The package is zero-runtime-dependency TypeScript. **In the monorepo**, it is
+built and tested from the repo root after a single root `npm install` (it shares
+the root's dev toolchain; it is not a separately-installed workspace):
+
+```bash
+# from the monorepo root:
+npm install                                                   # once
+cd packages/fullstackgtm && npm run build                     # tsc → dist/ (cleans first)
+node --experimental-strip-types --test tests/fullstackgtm*.test.ts   # from the repo ROOT — tests live there
+node packages/fullstackgtm/src/bin.ts doctor                  # run the CLI locally
+```
+
+> **Tests live at the monorepo root `tests/`, not in the package.** Running
+> `npm test` *inside* `packages/fullstackgtm` deliberately fails with a pointer
+> (a `pretest` guard) rather than silently passing with zero tests. On the
+> published mirror, `tests/` is present and `npm test` works there.
+
+**Node:** the published runtime supports Node ≥ 20 (`engines`), but the test
+runner needs Node **≥ 22.6** for `--experimental-strip-types`. Develop on 22.6+.
+
+Keep the core dependency-free — a new runtime dependency needs a very strong
+reason (the MCP server's `@modelcontextprotocol/sdk`/`zod` are optional peers,
+imported only by the MCP entrypoints).
+
+## Safety invariants (do not weaken)
+
+- Audits/suggests are read-only; nothing is written without explicit approval.
+- `apply` writes only operations whose ids were approved; `requires_human_*`
+  placeholders are refused without a concrete `--value`.
+- Approvals are HMAC-signed and re-verified at apply (integrity.ts) — a plan
+  edited after approval is refused.
+- Irreversible ops (merge/archive) get a fresh-snapshot drift guard; archiving a
+  record that still shares an identity key with another is refused.
+- Secrets are never accepted as argv flags — stdin or env only.
+- Finding/operation ids stay stable hashes of rule + record.
+
+When in doubt, add a test in `tests/fullstackgtm*.test.ts` (the suite doubles as
+the spec) and run the security suite (`fullstackgtmSecurity.test.ts`).
+
+## Releasing (maintainers)
+
+The steps are below (deeper rationale lives in `docs/open-core-boundary.md` in
+the development monorepo). From the monorepo:
+
+1. Bump `packages/fullstackgtm/package.json` version + add a `CHANGELOG.md`
+   entry; merge to `main`.
+2. `scripts/sync-oss.sh --push` (builds a fresh `dist/`, mirrors the package +
+   rewritten tests to `fullstackgtm/core`).
+3. Re-check the mirror's `package.json` version, then tag `vX.Y.Z` on the mirror
+   and push the tag.
+4. GitHub Actions (`release.yml`) publishes to npm via **OIDC trusted
+   publishing** — no tokens. It rebuilds from source and refuses to publish if
+   the committed `dist/` differs from a fresh build (supply-chain gate).
+
+**Access a new co-maintainer needs to cut a release:** write access to
+`github.com/fullstackgtm/core` (for `sync-oss.sh --push` and the tag push). No
+npm token is required — publishing is OIDC-bound to the repo + `release.yml`.
+Cut one supervised patch release end-to-end before taking over release duty.

package/README.md

@@ -219,7 +219,7 @@ fullstackgtm diff --before old.json --after new.json --fail-on-new-findings
 - `--demo` (with `--seed`) generates a realistic mid-market CRM with injected real-world failure modes — departed owners, unlinked deals, orphan accounts, stale pipeline — so agents and CI can exercise the full snapshot → audit → apply pipeline with zero credentials.
 - Exit codes: `0` success, `1` error, `2` findings at/above `--fail-on`.
 
-"Built for agents" is measured, not asserted: a 1,020-run benchmark (17 scenarios = 14 synthetic + 3 seeded from an anonymized real portal, × 3 tool-surface arms × 4 trials, across five models from three vendors, deterministic graders over final CRM state, τ-bench-style pass^k) shows the gated CLI surface beating raw CRM-API access on completion-under-policy for every model tested — and the tool-surface effect is monotonic and vendor-independent. Full matrix and methodology: [the leaderboard](./evals/crm/leaderboard/RESULTS.md).
+"Built for agents" is measured, not asserted: a 1,088-run benchmark (17 scenarios = 14 synthetic + 3 seeded from an anonymized real portal, × 3 tool-surface arms × 4 trials, across six models from three vendors, deterministic graders over final CRM state, τ-bench-style pass^k) shows the gated CLI surface beating raw CRM-API access on completion-under-policy for every model tested — and the tool-surface effect is monotonic and vendor-independent. Full matrix and methodology: [the leaderboard](./evals/crm/leaderboard/RESULTS.md).
 
 The design is **deterministic apply, governed suggest**: the parts that touch your CRM — the audit rules, the plan/apply contract, compare-and-set, the survivor/merge logic — are deterministic and replayable; the parts that read free text (`call parse`/`score`, `market classify`) are LLM-powered but bounded, with every quoted span mechanically verified against the source before it can drive a writeback. Nondeterministic suggestion, deterministic governance.
 

package/docs/architecture.md

@@ -0,0 +1,101 @@
+# Architecture
+
+A one-page map for someone about to change this code. The companion
+[api.md](./api.md) documents the contract surface by capability; this doc
+documents the *layout* and *data flow*.
+
+## The one idea
+
+**Deterministic apply, governed suggest.** Everything that touches a CRM is
+deterministic, replayable, and human-approved; anything that reads free text
+(call transcripts, competitor pages) is LLM-powered but bounded — its quoted
+evidence is mechanically verified against the source before it can drive a
+write. Hold this line when adding features.
+
+## Core data flow
+
+```
+provider  ──fetchSnapshot()──►  CanonicalGtmSnapshot
+                                      │
+                                      ▼
+                        audit (rules.ts × audit.ts)
+                                      │
+                                      ▼
+                               PatchPlan  (dry-run; typed operations)
+                                      │  suggest.ts fills requires_human_* values
+                                      ▼
+                         plans approve  (planStore.ts + integrity.ts: HMAC-signed)
+                                      │
+                                      ▼
+                    applyPatchPlan (connector.ts): for each APPROVED op —
+                    compare-and-set vs live value, precondition + guard recheck,
+                    irreversible-op drift guard → connector.applyOperation()
+                                      │
+                                      ▼
+                               PatchPlanRun  (the audit record; auditLog.ts exports it)
+```
+
+## Module map (`src/`)
+
+**Contracts & model**
+- `types.ts` — the canonical data model and every load-bearing contract
+  (`CanonicalGtmSnapshot`, `PatchPlan`/`PatchOperation`, `GtmConnector`,
+  `GtmAuditRule`). Read this first; each field is documented with *why* it exists.
+- `index.ts` — the public API manifest (one re-export block per module).
+
+**Audit → plan → apply (the governed loop)**
+- `rules.ts` — the 12 built-in deterministic audit rules + `GtmAuditRule` (the
+  public extension point) + stable-id hashing.
+- `audit.ts` — runs rules over a snapshot into a `PatchPlan`.
+- `suggest.ts` — derives concrete values for `requires_human_*` placeholders from
+  snapshot evidence, with confidence + reasons.
+- `planStore.ts` — durable plan lifecycle (save / approve / record runs), 0600.
+- `integrity.ts` — HMAC-signs approvals (per-install key) and verifies at apply.
+- `connector.ts` — `applyPatchPlan`: the safety contract (approval filter,
+  placeholder refusal, CAS, precondition/guard recheck, irreversible-op drift
+  guard). Provider-agnostic.
+- `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.
+- `resolve.ts` — the create-gate (exists / ambiguous / safe_to_create).
+
+**Connectors** (`connectors/`)
+- `hubspot.ts`, `salesforce.ts`, `stripe.ts` + their `*Auth.ts` OAuth/device
+  flows. A connector implements `GtmConnector` (`fetchSnapshot`, optional
+  `applyOperation`/`readField`/`fetchChanges`). `mappings.ts` holds field maps.
+
+**Free-text layers (LLM-bounded)**
+- `calls.ts` + `llm.ts` — transcript parse/score; LLM insights pass a verbatim
+  span gate before becoming evidence/writes.
+- `market*.ts` (`market.ts`, `marketClassify.ts`, `marketAxes.ts`,
+  `marketOverlay.ts`, `marketScale.ts`, `marketReport.ts`) — the competitive
+  market-map layer; classifications are verbatim-verified against captures.
+- `enrich.ts` + `enrichApollo.ts` — third-party data enrichment (fill-blanks).
+
+**Surfaces & infra**
+- `cli.ts` — one async function per command, flat dispatch in `runCli`;
+  orchestration only (all logic lives in the modules above). `bin.ts` is the
+  entrypoint. `mcp.ts`/`mcp-bin.ts` — the MCP server (optional peers).
+- `credentials.ts` — credential store (0600 file, or OS keychain via
+  `keychain.ts` when `FSGTM_KEYCHAIN=1`); broker pairing client.
+- `schedule.ts` — local cron provider (read/plan-side allowlist; never
+  auto-approves). `report.ts`/`format.ts` — rendering. `config.ts`,
+  `profiles.ts`, `sampleData.ts`.
+
+## Where do I add…
+
+- **a new audit rule** → implement `GtmAuditRule`, register it; see api.md
+  "Write a custom rule". Add a `tests/fullstackgtm*.test.ts`.
+- **a new connector** → implement `GtmConnector`; see api.md "Use a connector
+  programmatically".
+- **a new operation type** → extend `PatchOperationType` in types.ts, handle it
+  in `connector.ts` apply + each connector's `applyOperation`, and decide its
+  safety class (does it need CAS / a drift guard / approval signing coverage?).
+
+## Tests as spec
+
+`tests/fullstackgtm*.test.ts` (at the **monorepo root**, run from there) map
+one-to-one onto modules; `fullstackgtmSecurity.test.ts` pins the safety
+invariants. Change apply/connector/integrity code → run the security suite.

package/docs/roadmap-to-1.0.md

@@ -106,7 +106,7 @@ The original thesis: GTM data disagrees across systems.
 - Docs site with the operating-model registry as browsable reference.
 - Performance pass: streaming snapshots for very large orgs.
 
-## 0.10 → 0.25 — the layers, as shipped
+## 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:
@@ -129,9 +129,19 @@ outward, one layer per release, each consolidating before the next expanded:
 - **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.
 
 The known-gaps list below predates these layers and has been re-verified
-against the 0.25 surface: still accurate, still open.
+against the 0.28 surface: still accurate, still open.
 
 ## Known real-portal gaps to close before 1.0
 

package/llms.txt

@@ -15,6 +15,8 @@ at/above `--fail-on`.
 - [README](https://github.com/fullstackgtm/core/blob/main/README.md): install, five-minute loop, auth ladder, MCP setup, programmatic use
 - [INSTALL_FOR_AGENTS](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md): deterministic install-and-verify steps with expected outputs
 - [Agent skill](https://github.com/fullstackgtm/core/blob/main/skills/fullstackgtm/SKILL.md): compact operating guide, installable via `npx skills add fullstackgtm/core`
+- [Architecture](https://github.com/fullstackgtm/core/blob/main/docs/architecture.md): module map + snapshot → audit → plan → apply data flow; "where do I add a rule/connector/operation"
+- [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
 - [CHANGELOG](https://github.com/fullstackgtm/core/blob/main/CHANGELOG.md): release history

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.28.1",
+  "version": "0.28.3",
   "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)",
@@ -29,6 +29,7 @@
     "README.md",
     "CHANGELOG.md",
     "INSTALL_FOR_AGENTS.md",
+    "CONTRIBUTING.md",
     "llms.txt",
     "skills",
     "LICENSE",
@@ -38,6 +39,7 @@
   ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "pretest": "test -d tests || { echo 'No tests/ in this directory. In the published mirror, tests live here and `npm test` works. In the monorepo, run package tests from the repo ROOT: `node --experimental-strip-types --test tests/fullstackgtm*.test.ts` (the tests live at the monorepo root tests/).' >&2; exit 1; }",
     "test": "node --experimental-strip-types --test tests/*.test.ts",
     "prepublishOnly": "npm run build"
   },