fullstackgtm 0.23.1 → 0.23.2

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.23.2] — 2026-06-12
+
+Documentation catch-up: the README, llms.txt, and docs/api.md now cover
+everything that shipped 0.19–0.23. (No code changes.)
+
+### Fixed
+
+- README: new "Routine maintenance as governed verbs" section (`bulk-update`,
+  `dedupe`, `reassign`, `fix`) and a market-map paragraph for `market overlay`
+  (directives from your own ground truth) and `market scale` (citable,
+  calibrated size estimates).
+- llms.txt: governed-write-verbs invariants block; overlay/scale invariants
+  added to the market-map block.
+- docs/api.md: CLI command list completed (write verbs, `enrich`, market
+  `overlay`/`scale`); new "Governed write verbs" and "Enrich" export
+  sections; market-map section updated for 0.16–0.23 exports incl.
+  `computeDirectives`/`directivesToPlan` and `computeScaleIndex`.
+
 ## [0.23.1] — 2026-06-12
 
 ### Fixed

package/README.md

@@ -109,6 +109,22 @@ npx fullstackgtm report --provider hubspot --client "Acme" --out acme-health.htm
 
 `report` renders the same audit as a deliverable — severity counts up front, a prose summary, per-rule detail with example records, and next steps — as markdown or self-contained HTML (printable, emailable, no external assets).
 
+## Routine maintenance as governed verbs: bulk-update, dedupe, reassign, fix
+
+The maintenance work RevOps actually does in bulk — backfills, book transfers, duplicate sweeps, "just fix everything that rule found" — gets first-class verbs. Each one *builds a plan*; nothing executes without the same approve → apply gauntlet as everything else.
+
+```bash
+fullstackgtm bulk-update deal --where "stage=closedwon" --where "amount:empty" \
+  --set amount=from:account.annualrevenue --save     # per-record derived values; empty sources skipped, never guessed
+fullstackgtm dedupe account --key domain --keep richest --save   # one merge_records op per duplicate group
+fullstackgtm reassign --from 411 --to 902 --except-deal-stage closing --save   # ownership handoff playbook
+fullstackgtm fix --rule missing-deal-owner --provider hubspot --yes  # audit one rule → suggest → approve → apply, one command
+```
+
+`bulk-update` filters the snapshot (`=`, `!=`, `~` substring, `:empty`/`:notempty`, `|` any-of, relational pseudo-fields like `account.domain` or `openDealStages`) into a dry-run patch plan — and **the full filter is re-verified per record at apply time**, with mid-apply rechecks, so a record that stopped matching between audit and apply is skipped, not clobbered. Equality filters double as preconditions; `--require` adds explicit ones; `--guard` asserts cross-record conditions; `--max-operations` caps blast radius. `--set field=from:<sourceField>` derives values per record; `--archive` refuses records whose identity key (account domain, contact email) is shared with another record — that's a duplicate, and duplicates are merged with `dedupe`, not archived around.
+
+`dedupe` finds duplicate groups by normalized identity key and emits one `merge_records` operation per group with a deterministic survivor (`richest` = most populated fields, ties to lowest id; `oldest`). Merges stay irreversible-and-therefore-low-confidence-capped on approval, exactly like merge suggestions from the audit. `reassign` is the ownership-handoff playbook: one plan per object type, extra scoping account-lifted to deals and contacts, and `--except-deal-stage` excludes both deals in that stage and every record whose account has an open deal in it. `fix` is the one-shot composite for a single rule: audit → save → suggest → approve suggestion-backed operations at the confidence bar → with `--yes`, apply and print the stage-by-stage summary; without it, stop after approval and print the apply command.
+
 ## The market map: the category, observed
 
 Your CRM records what happened in your own deals; nothing records the shape of the category you sell into. The **market map** does: vendors and a claim taxonomy live in a reviewable `market.config.json`, vendor pages are captured into a content-addressed cache, every vendor × claim cell gets a messaging-intensity reading (LOUD / QUIET / ABSENT — with UNOBSERVABLE for failed captures, never a fake absence), and deterministic front states fall out per claim: open, contested, owned, saturated.
@@ -126,6 +142,8 @@ The discipline matches the rest of the tool. Intensity readings are *proposals*
 
 `market axes` is for earning a strategic 2×2 instead of asserting one: PCA over the intensity matrix (PC1 = the category's own primary axis, PC2 = the most differentiating direction orthogonal to it), triangulation of your configured axes against the data, and an orthogonality screen that flags two axes that are secretly one. Axes are claim-scoring rubrics in the config; the report renders the primary pair as the strategic map. Captures and observations are profile-scoped (`~/.fullstackgtm/market/<category>`), so one client's category intel never bleeds into another's.
 
+Two more derivations close the loop from map to action. `market overlay --snapshot <crm.json> [--calls <files>]` joins the observation store against your own ground truth — which claims and vendors actually come up in your deals and call transcripts (deterministic word-boundary matching, no LLM) — and emits OCCUPY / PROMOTE / URGENT / RETREAT directives, each carrying at least one observation and one CRM stat with its sample size; below the evidence thresholds the honest answer is *no directive*. `--save` turns directives into approval-gated `create_task` operations through the normal plan chain. `market scale` estimates each vendor's size from **citable** signals you record in the config (G2 review counts, LinkedIn headcount, revenue claims — each with source URL, verbatim quote, and caveat): every signal is converted into revenue space first, calibrated within the vendor set and stratified by ACV band, then combined as a weighted geometric mean with the uncertainty spread and calibration table disclosed. The report's strategic-map bubbles become area-proportional to estimated revenue share — captioned "citable but NOT audited" — and without signals, dots are uniform and the caption says size carries no meaning.
+
 ## Governed enrichment: a diff you approve before third-party data touches your CRM
 
 Every enrichment vendor ships fire-and-forget writeback. The **enrich layer** inverts that: declare once which fields come from which source under which conflict policy (`enrich.config.json` — sources, ordered match keys, field mappings, policy), then `enrich append` fills the gaps and `enrich refresh` keeps them current — with every write passing through the normal dry-run → approval → apply contract, and every value traceable to the source payload that produced it.

package/docs/api.md

@@ -59,8 +59,10 @@ release.
 
 Commands: `login` / `logout`, `snapshot`, `audit`, `report`, `diff`, `merge`, `plans`,
 `apply`, `suggest`, `call` (`parse` / `score` / `link` / `plan`), `resolve`,
+`bulk-update`, `dedupe`, `reassign`, `fix`,
 `market` (`init` / `capture` / `classify` / `worksheet` / `observe` / `fronts` /
-`axes` / `report` / `refresh`), `rules`, `profiles`, `doctor`.
+`axes` / `overlay` / `scale` / `report` / `refresh`),
+`enrich` (`append` / `refresh` / `ingest` / `status`), `rules`, `profiles`, `doctor`.
 Exit codes: `0` success · `1` error · `2` findings/regressions at the requested gate
 (`--fail-on`, `--fail-on-new-findings`). `--json` everywhere; JSON output shapes are stable.
 
@@ -80,19 +82,59 @@ deliverable in markdown or self-contained HTML: severity counts, prose summary,
 per-rule detail with capped examples, and next steps. `auditReportToMarkdown` /
 `auditReportToHtml` expose the same rendering programmatically.
 
+## Governed write verbs
+
+Plan builders behind `bulk-update`, `dedupe`, and `reassign` — every one
+emits a standard dry-run `PatchPlan` for the normal approve → apply chain:
+
+- `buildBulkUpdatePlan(snapshot, options: BulkUpdateOptions)` with
+  `parseWhere` (filter expressions: `=`, `!=`, `~`, `!~`, `:empty`,
+  `:notempty`, `|` any-of, relational pseudo-fields) and
+  `isFilterableField`. Filters are re-verified per record at apply time;
+  `from:<sourceField>` values derive per record from the snapshot.
+- `buildDedupePlan(snapshot, options: DedupeOptions)` with `dedupeKey` —
+  duplicate groups by normalized identity key, one `merge_records` per group,
+  deterministic survivor selection (`richest` / `oldest`).
+- `buildReassignPlans(snapshot, options: ReassignOptions)` — one plan per
+  `ReassignObjectType`, account-lifted scoping, stage exclusions.
+
+`fix` is CLI-only composition of existing surfaces (audit → suggest →
+approve → apply for one rule).
+
+## Enrich
+
+Governed third-party enrichment (spec-first; `enrich.config.json` validated
+by `parseEnrichConfig` / `loadEnrichConfig`, types `EnrichConfig`,
+`EnrichFieldConfig`, `EnrichSourceConfig`): `buildEnrichPlan` matches staged
+or pulled source records to CRM records (`matchSourceRecord` — ordered keys,
+`MatchOutcome` of matched / unmatched / ambiguous) and emits fill-blanks-only
+operations. `createFileEnrichRunStore` / `EnrichRunStore` is the profile-scoped
+append-only run store (resume cursor, per-record/per-field `enrichedAt`
+stamps read by `latestStamps` / `selectStaleWork`). `parseCsv` is the
+dependency-free CSV intake; the Apollo client (`createApolloClient`,
+`pullApolloRecords`, 429-aware with `Retry-After`) is the first `api`-kind
+source.
+
 ## Market map
 
-Newer surface (0.16–0.18); shapes are settling toward the 1.0 contract. A live
+Newer surface (0.16–0.23); shapes are settling toward the 1.0 contract. A live
 model of the competitive category: claim taxonomy + vendor registry as a
 reviewable `market.config.json` (`MarketConfig`, `MarketClaim`, `MarketVendor`,
-`MarketAxis`), content-addressed page captures (`captureMarket`,
-`loadCaptureTexts`), append-only observations (`ObservationSet`,
-`MarketObservation`, `ObservationStore` / `createFileObservationStore` —
-profile-scoped under `<home>/market/<category>`), and deterministic
-derivations: `computeFrontStates` / `diffFrontStates` (front rule v1),
-`assessAxes` / `pcaTop2` / `axisPosition` (axis discovery), and
+`MarketAxis` — axes require `negativePole`/`positivePole` labels), content-addressed
+page captures (`captureMarket`, `loadCaptureTexts`), append-only observations
+(`ObservationSet`, `MarketObservation`, `ObservationStore` /
+`createFileObservationStore` — profile-scoped under `<home>/market/<category>`),
+and deterministic derivations: `computeFrontStates` / `diffFrontStates`
+(front rule v1), `assessAxes` / `pcaTop2` / `axisPosition` (axis discovery),
+`computeDirectives` / `computeOverlayStats` / `directivesToPlan`
+(`market overlay` — observations × CRM snapshot × call corpus →
+OCCUPY/PROMOTE/URGENT/RETREAT `MarketDirective`s, convertible to an
+approval-gated plan of `create_task` operations), `computeScaleIndex` /
+`scaleReportToText` (`market scale` — citable `ScaleSignal`s → within-set,
+ACV-band-stratified revenue estimates with disclosed uncertainty), and
 `marketMapToMarkdown` / `marketMapToHtml` (the field report; renders the
-primary strategic 2×2 when `axes` / `primaryAxes` are configured).
+primary strategic 2×2 when `axes` / `primaryAxes` are configured, bubbles
+area-proportional to estimated revenue share when scale signals exist).
 
 Intensity readings are proposals: `classifyMarket` (LLM, bring-your-own-key,
 provenance-marked) or `buildWorksheet` + `market observe` (agent/human). Every

package/llms.txt

@@ -44,9 +44,34 @@ elsewhere). Failed captures read UNOBSERVABLE, never ABSENT. `fronts --diff`
 = deterministic front states + drift between runs; `axes` = PCA axis
 discovery + orthogonality screen; `report` = self-contained HTML field
 report; `refresh` = capture → classify → drift → report in one command.
+`overlay --snapshot <crm.json> [--calls <files>]` joins observations to YOUR
+CRM/calls (deterministic mention matching, no LLM) and emits OCCUPY/PROMOTE/
+URGENT/RETREAT directives — each needs ≥1 observation + ≥1 CRM stat with
+sample size; below thresholds = no directive; `--save` = approval-gated
+create_task ops. `scale` = citable scaleSignals (sourceUrl + verbatim quote
+each) → revenue-space estimates calibrated within-set by acvBand, disclosed
+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 (governed write verbs)
+
+`bulk-update <object> --where … (--set|--archive|--create-task)` filters the
+snapshot into a dry-run plan; the FULL filter is re-verified per record at
+apply time (plus mid-apply rechecks); equality filters double as
+preconditions, `--require`/`--guard` add explicit ones, `--max-operations`
+caps blast radius. `--set f=from:<source>` derives per-record values (empty
+source = skip + count, never guess). `--archive` refuses records sharing an
+identity key — merge with `dedupe` instead. `dedupe <object> --key
+<domain|email|name>` = one merge_records op per duplicate group,
+deterministic survivor (`--keep richest|oldest`); merges are irreversible and
+stay low-confidence-capped at approval. `reassign --from <owner> --to
+<owner>` = ownership handoff plans per object type; `--except-deal-stage`
+also excludes records whose account has an open deal in that stage. `fix
+--rule <id>` = audit one rule → suggest → approve at the confidence bar →
+apply only with `--yes`. All four produce plans; none writes outside
+approve → apply.
+
 ## Key invariants (enrich)
 
 `fullstackgtm enrich` is governed enrichment: `append` pulls (Apollo, BYO key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.23.1",
+  "version": "0.23.2",
   "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",