fullstackgtm 0.16.0 → 0.18.0

package/docs/api.md

@@ -58,7 +58,9 @@ release.
 ## CLI
 
 Commands: `login` / `logout`, `snapshot`, `audit`, `report`, `diff`, `merge`, `plans`,
-`apply`, `rules`, `profiles`, `doctor`.
+`apply`, `suggest`, `call` (`parse` / `score` / `link` / `plan`), `resolve`,
+`market` (`init` / `capture` / `classify` / `worksheet` / `observe` / `fronts` /
+`axes` / `report` / `refresh`), `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.
 
@@ -78,7 +80,32 @@ 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.
 
+## Market map
+
+Newer surface (0.16–0.18); 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
+`marketMapToMarkdown` / `marketMapToHtml` (the field report; renders the
+primary strategic 2×2 when `axes` / `primaryAxes` are configured).
+
+Intensity readings are proposals: `classifyMarket` (LLM, bring-your-own-key,
+provenance-marked) or `buildWorksheet` + `market observe` (agent/human). Every
+quoted evidence span is mechanically verified verbatim
+(`verifyEvidenceSpans`; whitespace and punctuation-spacing normalized) against
+the stored capture it cites before a set is accepted; failed captures read as
+`unobservable`, never `absent`.
+
 ## MCP
 
 Tools: `fullstackgtm_audit`, `fullstackgtm_rules`, `fullstackgtm_apply`
-(requires explicit `approvedOperationIds`). Input schemas are stable.
+(requires explicit `approvedOperationIds`), `fullstackgtm_suggest`,
+`fullstackgtm_call_parse`, `fullstackgtm_resolve`,
+`fullstackgtm_market_worksheet`, `fullstackgtm_market_observe` (validates,
+verifies quoted spans against the stored captures, appends, returns front
+states). Input schemas are stable.

package/llms.txt

@@ -31,6 +31,22 @@ coaching scorecards; `call link` suggests the deal with confidence + reason;
 `call plan` proposes governed next-step writes through the standard
 approve/apply lifecycle.
 
+## Key invariants (market map)
+
+`fullstackgtm market` models the competitive category: vendors + claim
+taxonomy in `market.config.json`; `capture` stores vendor pages
+content-addressed; `classify` (BYO key, same ladder as calls) or
+`worksheet` + `observe` (agent/human channel) propose LOUD/QUIET/ABSENT
+intensity readings per vendor × claim. Every quoted evidence span is
+mechanically verified verbatim against the stored capture it cites;
+unverifiable quotes are rejected (`--unverified` only when captures live
+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.
+Storage is profile-scoped under `<home>/market/<category>`. MCP:
+`fullstackgtm_market_worksheet`, `fullstackgtm_market_observe`.
+
 ## Key invariants
 
 - Reads are safe by default; nothing is written without explicit `--approve`

package/package.json

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

package/src/cli.ts

@@ -44,11 +44,15 @@ import {
   computeFrontStates,
   createFileObservationStore,
   diffFrontStates,
+  loadCaptureTexts,
   loadMarketConfig,
   starterMarketConfig,
   validateObservationSet,
+  verifyEvidenceSpans,
   type ObservationSet,
 } from "./market.ts";
+import { assessAxes, axesReportToText } from "./marketAxes.ts";
+import { buildWorksheet, classifyMarket } from "./marketClassify.ts";
 import { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 import {
   DEFAULT_RUBRIC,
@@ -107,13 +111,19 @@ Usage:
                                                found (exists/ambiguous) — call before ANY record creation
   fullstackgtm market init --category <name>   start a market map: vendors + claim taxonomy as reviewable config
   fullstackgtm market capture [--config <path>] [--run <label>]
-  fullstackgtm market observe --from <observations.json>
+  fullstackgtm market classify [--run <label>] [--vendor <id>] [--model m] [--out <path>]
+  fullstackgtm market worksheet --vendor <id> [--out <path>]
+  fullstackgtm market observe --from <observations.json> [--unverified]
   fullstackgtm market fronts [--run <label>] [--diff <prior-run>] [--json]
+  fullstackgtm market axes [--run <label>] [--json]
   fullstackgtm market report [--run <label>] [--format md|html] [--out <path>]
+  fullstackgtm market refresh [--run <label>] [--model m]
                                                the live competitive map: capture vendor pages (content-addressed),
-                                               ingest intensity readings with verbatim-quote evidence, compute
-                                               deterministic front states (open/contested/owned/saturated) and
-                                               drift between runs, render the client-ready field report
+                                               classify intensity per claim (LLM bring-your-own-key, or fill the
+                                               worksheet with any agent) — every quoted span is verified verbatim
+                                               against the stored capture it cites before it's accepted — then
+                                               compute deterministic front states and drift, render the field
+                                               report. refresh = capture → classify → drift → report in one step
   fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
                                                derive values for requires_human_* placeholders
                                                from snapshot evidence, with confidence + reasons
@@ -696,15 +706,22 @@ the free keyword baseline; score always needs a key (scoring is LLM work).`);
  * TTY a missing key is captured once (validated, stored 0600 like provider
  * logins). Non-interactive contexts get an actionable error instead.
  */
-async function requireLlmCredential(command: "parse" | "score" = "parse"): Promise<{ provider: LlmProvider; apiKey: string }> {
+async function requireLlmCredential(
+  command: "parse" | "score" | "market classify" = "parse",
+): Promise<{ provider: LlmProvider; apiKey: string }> {
   const resolved = resolveLlmCredential();
   if (resolved) return resolved;
   // Scoring is inherently LLM work — there is no keyword fallback to suggest.
   const fallbackHint =
-    command === "parse" ? ", or pass --deterministic for the free keyword baseline" : " (call score has no non-LLM mode)";
+    command === "parse"
+      ? ", or pass --deterministic for the free keyword baseline"
+      : command === "score"
+        ? " (call score has no non-LLM mode)"
+        : ", or classify by hand: `market worksheet --vendor <id>` then `market observe --from`";
+  const work = command === "score" ? "scoring" : command === "parse" ? "extraction" : "classification";
   if (!process.stdin.isTTY) {
     throw new Error(
-      `LLM ${command === "score" ? "scoring" : "extraction"} needs an API key. Set ANTHROPIC_API_KEY or OPENAI_API_KEY, or run \`echo "$KEY" | fullstackgtm login anthropic\` (or \`login openai\`) once${fallbackHint}.`,
+      `LLM ${work} needs an API key. Set ANTHROPIC_API_KEY or OPENAI_API_KEY, or run \`echo "$KEY" | fullstackgtm login anthropic\` (or \`login openai\`) once${fallbackHint}.`,
     );
   }
   console.error("LLM parsing needs an API key (Anthropic or OpenAI) — yours, used directly with the provider.");
@@ -824,9 +841,11 @@ function buildCallPlan(
 /**
  * The market map: claim taxonomy in a reviewable config file, page captures
  * and append-only observations under the profile home, deterministic front
- * states and reports computed from the store. Classification (LLM intensity
- * readings) lands in a later change; until then `market observe --from`
- * ingests proposal files produced by an agent or a human.
+ * states and reports computed from the store. Intensity readings enter as
+ * proposals through two channels — `classify` (LLM, bring-your-own-key, the
+ * call-intelligence pattern) and `worksheet`/`observe` (an agent or human
+ * fills the worksheet) — and BOTH pass the same mechanical gate: every quoted
+ * span is verified verbatim against the stored capture it cites.
  */
 async function marketCommand(args: string[]) {
   const [subcommand, ...rest] = args;
@@ -836,9 +855,26 @@ async function marketCommand(args: string[]) {
     console.log(`Usage:
 market init --category <name> [--out <path>]   write a starter market.config.json
 market capture [--config <path>] [--run <label>]
-market observe --from <observations.json> [--config <path>]
+market classify [--run <label>] [--capture-run <label>] [--vendor <id>] [--model m] [--out <path>]
+market worksheet --vendor <id> [--capture-run <label>] [--out <path>]
+market observe --from <observations.json> [--unverified]
 market fronts [--config <path>] [--run <label>] [--diff <prior-run>] [--json]
+market axes [--config <path>] [--run <label>] [--json]
 market report [--config <path>] [--run <label>] [--format md|html] [--out <path>]
+market refresh [--run <label>] [--model m]     capture → classify → fronts drift → HTML report
+
+axes runs the axis-discovery math: PCA over the vendor × claim intensity
+matrix (PC1 = the category's primary axis, PC2 = the max-differentiation
+direction orthogonal to it), triangulation of configured axes against the
+PCs, and an orthogonality screen (|r|>0.75 = one axis twice). Axes live in
+the config as claim-scoring rubrics; the report's strategic map and axis
+lab render from them.
+
+classify uses your Anthropic/OpenAI key (like call parse) to read the stored
+captures and propose intensity readings; worksheet is the no-key path (an
+agent or human fills it, submits via observe). Either way, every quoted span
+is verified character-for-character against the capture it cites before the
+observation is accepted — quotes that aren't on the page bounce.
 
 The taxonomy (vendors + claims) is config you review and version; captures
 and observations live under ~/.fullstackgtm/market/<category> (profile-scoped,
@@ -883,11 +919,100 @@ recomputed deterministically on every invocation — never stored.`);
       process.exitCode = 1;
       return;
     }
+    if (!rest.includes("--unverified")) {
+      const { textByHash } = loadCaptureTexts(config.category);
+      const failures = verifyEvidenceSpans(set.observations, textByHash);
+      if (failures.length > 0) {
+        console.error(`Rejected: ${failures.length} evidence span(s) failed verification against the stored captures`);
+        for (const failure of failures.slice(0, 20)) {
+          console.error(`  - ${failure.vendorId} × ${failure.claimId}: ${failure.problem}`);
+        }
+        console.error("Quotes must be copied verbatim from the captured pages. (--unverified skips this gate when the captures genuinely live elsewhere.)");
+        process.exitCode = 1;
+        return;
+      }
+    }
     await store.append(set);
     console.log(`Appended ${set.runLabel}: ${set.observations.length} observations (${set.extractor})`);
     return;
   }
 
+  if (subcommand === "worksheet") {
+    const vendorId = option(rest, "--vendor");
+    if (!vendorId) throw new Error("market worksheet requires --vendor <id>");
+    const worksheet = buildWorksheet(config, vendorId, { captureRun: option(rest, "--capture-run") ?? undefined });
+    const outPath = option(rest, "--out");
+    const payload = `${JSON.stringify(worksheet, null, 2)}\n`;
+    if (outPath) {
+      writeFileSync(resolve(process.cwd(), outPath), payload);
+      console.log(`Wrote ${outPath} (${worksheet.pages.length} captured pages, ${worksheet.claims.length} claims)`);
+    } else {
+      console.log(payload);
+    }
+    return;
+  }
+
+  if (subcommand === "classify") {
+    const credential = await requireLlmCredential("market classify");
+    const vendorFilter = option(rest, "--vendor");
+    const outPath = option(rest, "--out");
+    if (vendorFilter && !outPath) {
+      throw new Error(
+        "market classify --vendor produces a partial set (coverage validation would reject it) — pass --out <path> to inspect/merge it by hand",
+      );
+    }
+    const result = await classifyMarket(config, {
+      llm: { ...credential, model: option(rest, "--model") ?? undefined },
+      runLabel: option(rest, "--run") ?? option(rest, "--capture-run") ?? "run-1",
+      captureRun: option(rest, "--capture-run") ?? undefined,
+      vendors: vendorFilter ? [vendorFilter] : undefined,
+    });
+    if (result.retriedVendorIds.length > 0) {
+      console.error(`Span verification bounced ${result.retriedVendorIds.join(", ")} once; retry passed.`);
+    }
+    if (outPath) {
+      writeFileSync(resolve(process.cwd(), outPath), `${JSON.stringify(result.set, null, 2)}\n`);
+      console.log(`Wrote ${outPath}: ${result.set.observations.length} verified observations (${result.set.extractor})`);
+      return;
+    }
+    const problems = validateObservationSet(config, result.set);
+    if (problems.length > 0) {
+      throw new Error(`Classified set failed validation: ${problems.slice(0, 5).join("; ")}`);
+    }
+    await store.append(result.set);
+    console.log(
+      `Appended ${result.set.runLabel}: ${result.set.observations.length} observations, every span verified (${result.set.extractor})`,
+    );
+    return;
+  }
+
+  if (subcommand === "refresh") {
+    const credential = await requireLlmCredential("market classify");
+    const runLabel = option(rest, "--run") ?? `run-${new Date().toISOString().slice(0, 10)}`;
+    const prior = await store.latest();
+    console.log(`Capturing ${config.vendors.length} vendors as ${runLabel}…`);
+    const captured = await captureMarket(config, { runLabel });
+    const failed = captured.entries.filter((entry) => !entry.captureHash);
+    if (failed.length > 0) console.log(`${failed.length} page(s) failed/empty — affected cells will verify against remaining pages or read unobservable.`);
+    console.log(`Classifying with ${credential.provider}…`);
+    const result = await classifyMarket(config, {
+      llm: { ...credential, model: option(rest, "--model") ?? undefined },
+      runLabel,
+      captureRun: runLabel,
+    });
+    await store.append(result.set);
+    const fronts = computeFrontStates(config, result.set);
+    if (prior) {
+      const drift = diffFrontStates(computeFrontStates(config, prior), fronts);
+      if (drift.length === 0) console.log(`No front changes since ${prior.runLabel}.`);
+      for (const change of drift) console.log(`CHANGED   ${change.claimId}: ${change.before} → ${change.after}`);
+    }
+    const outPath = option(rest, "--out") ?? `${config.category}-${runLabel}.html`;
+    writeFileSync(resolve(process.cwd(), outPath), marketMapToHtml(config, result.set));
+    console.log(`Wrote ${outPath}`);
+    return;
+  }
+
   const loadSet = async (): Promise<ObservationSet> => {
     const runLabel = option(rest, "--run");
     const set = runLabel ? await store.get(runLabel) : await store.latest();
@@ -938,7 +1063,20 @@ recomputed deterministically on every invocation — never stored.`);
     return;
   }
 
-  throw new Error(`Unknown market subcommand: ${subcommand} (try: init, capture, observe, fronts, report)`);
+  if (subcommand === "axes") {
+    const set = await loadSet();
+    const report = assessAxes(config, set);
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+    console.log(axesReportToText(report));
+    return;
+  }
+
+  throw new Error(
+    `Unknown market subcommand: ${subcommand} (try: init, capture, classify, worksheet, observe, fronts, axes, report, refresh)`,
+  );
 }
 
 /**

package/src/index.ts

@@ -136,18 +136,22 @@ export {
   createFileObservationStore,
   diffFrontStates,
   extractReadableText,
+  loadCaptureTexts,
   loadMarketConfig,
   marketHome,
+  normalizeForMatch,
   observationId,
   parseMarketConfig,
   starterMarketConfig,
   validateObservationSet,
+  verifyEvidenceSpans,
   type CaptureEntry,
   type CaptureOptions,
   type ClaimFront,
   type ClaimIntensity,
   type FrontDrift,
   type FrontState,
+  type MarketAxis,
   type MarketClaim,
   type MarketConfig,
   type MarketObservation,
@@ -155,7 +159,27 @@ export {
   type ObservationConfidence,
   type ObservationSet,
   type ObservationStore,
+  type SpanVerificationFailure,
 } from "./market.ts";
+export {
+  assessAxes,
+  axesReportToText,
+  axisPosition,
+  messageBreadth,
+  pcaTop2,
+  pearson,
+  type AxesReport,
+  type AxisAssessment,
+  type AxisPairing,
+  type PrincipalComponent,
+} from "./marketAxes.ts";
+export {
+  buildWorksheet,
+  classifyMarket,
+  type ClassifyMarketOptions,
+  type ClassifyMarketResult,
+  type MarketWorksheet,
+} from "./marketClassify.ts";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export type {

package/src/llm.ts

@@ -239,7 +239,13 @@ export function parseRubric(json: string): Rubric {
 
 // ── Provider plumbing (raw fetch, forced tool calls) ───────────────────────
 
-async function forcedToolCall(
+/**
+ * Shared constrained-tool-call plumbing: force the model to answer through a
+ * single tool whose input_schema is the output contract. Exported for other
+ * semi-deterministic features (market classification) — every LLM feature in
+ * the package goes through this one seam.
+ */
+export async function forcedToolCall(
   prompt: string,
   toolName: string,
   schema: object,

package/src/market.ts

@@ -52,6 +52,19 @@ export type MarketVendor = {
   notes?: string;
 };
 
+export type MarketAxis = {
+  id: string;
+  label: string;
+  negativePole: string;
+  positivePole: string;
+  /** How a human scores a claim on this axis — the axis IS this rubric. */
+  rubric: string;
+  /** e.g. "validated", "proposal", "proposal (PC2-validated)". Reviewer-facing. */
+  status?: string;
+  /** claimId → score in [-1, 1]; null = the axis does not apply to this claim. */
+  claimScores: Record<string, number | null>;
+};
+
 export type MarketConfig = {
   category: string;
   anchorVendor?: string;
@@ -59,6 +72,10 @@ export type MarketConfig = {
   claims: MarketClaim[];
   /** The LOUD/QUIET/ABSENT/UNOBSERVABLE judging rule, stated for reviewers. */
   surfaceRule?: string;
+  /** Strategic axes as claim-scoring rubrics — config, not code. */
+  axes?: MarketAxis[];
+  /** [xAxisId, yAxisId] for the report's strategic map. */
+  primaryAxes?: [string, string];
 };
 
 export type MarketObservation = {
@@ -148,6 +165,27 @@ export function parseMarketConfig(raw: string): MarketConfig {
   if (config.anchorVendor && !config.vendors.some((v) => v.id === config.anchorVendor)) {
     throw new Error(`market config: anchorVendor "${config.anchorVendor}" is not in vendors`);
   }
+  if (config.axes) {
+    const claimIds = new Set(config.claims.map((claim) => claim.id));
+    const axisIds = new Set<string>();
+    for (const axis of config.axes) {
+      if (!axis.id) throw new Error("market config: axis missing id");
+      if (axisIds.has(axis.id)) throw new Error(`market config: duplicate axis id "${axis.id}"`);
+      axisIds.add(axis.id);
+      for (const claimId of Object.keys(axis.claimScores ?? {})) {
+        if (!claimIds.has(claimId)) {
+          throw new Error(`market config: axis "${axis.id}" scores unknown claim "${claimId}"`);
+        }
+      }
+    }
+    if (config.primaryAxes) {
+      if (config.primaryAxes.length !== 2 || config.primaryAxes.some((id) => !axisIds.has(id))) {
+        throw new Error(`market config: primaryAxes must name two configured axes (got ${JSON.stringify(config.primaryAxes)})`);
+      }
+    }
+  } else if (config.primaryAxes) {
+    throw new Error("market config: primaryAxes set but no axes configured");
+  }
   return config;
 }
 
@@ -408,6 +446,98 @@ export function validateObservationSet(config: MarketConfig, set: ObservationSet
   return problems;
 }
 
+// ---------------------------------------------------------------------------
+// Evidence span verification — the deterministic gate that makes the
+// verbatim-quote rule mechanical instead of a prompt instruction. Because the
+// source documents are *stored* (unlike call transcripts, which pass through),
+// every quoted span can be checked against the capture it cites before the
+// observation is accepted. Comparison is whitespace-normalized only: case and
+// wording must match the page exactly.
+
+export function loadCaptureTexts(
+  category: string,
+  directory?: string,
+): { entries: CaptureEntry[]; textByHash: Map<string, string> } {
+  const dir = directory ?? join(marketHome(category), "captures");
+  const manifestPath = join(dir, "manifest.json");
+  const entries: CaptureEntry[] = existsSync(manifestPath)
+    ? (JSON.parse(readFileSync(manifestPath, "utf8")) as CaptureEntry[])
+    : [];
+  const textByHash = new Map<string, string>();
+  for (const entry of entries) {
+    if (entry.captureHash && !textByHash.has(entry.captureHash)) {
+      try {
+        textByHash.set(entry.captureHash, readFileSync(join(dir, `${entry.captureHash}.txt`), "utf8"));
+      } catch {
+        // Missing capture file: verification of anything citing it will fail loudly.
+      }
+    }
+  }
+  return { entries, textByHash };
+}
+
+/**
+ * Whitespace-only normalization for span matching, plus one extraction
+ * artifact: the HTML-to-text step can emit a line break before punctuation
+ * that follows an inline tag ("placements\n. Districts"), which no honest
+ * quoter would reproduce — so whitespace *before* punctuation is dropped
+ * too. Words, casing, and characters must still match the page exactly.
+ */
+export function normalizeForMatch(value: string): string {
+  return value
+    .replace(/\s+([.,;:!?])/g, "$1")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export type SpanVerificationFailure = {
+  vendorId: string;
+  claimId: string;
+  quote: string;
+  problem: string;
+};
+
+export function verifyEvidenceSpans(
+  observations: MarketObservation[],
+  textByHash: Map<string, string>,
+): SpanVerificationFailure[] {
+  const failures: SpanVerificationFailure[] = [];
+  for (const obs of observations) {
+    for (const evidence of obs.evidence) {
+      const quote = evidence.text ?? "";
+      const hash = String(evidence.metadata?.captureHash ?? "");
+      if (!hash) {
+        failures.push({
+          vendorId: obs.vendorId,
+          claimId: obs.claimId,
+          quote,
+          problem: "evidence has no captureHash — spans must cite a stored capture",
+        });
+        continue;
+      }
+      const captureText = textByHash.get(hash);
+      if (captureText === undefined) {
+        failures.push({
+          vendorId: obs.vendorId,
+          claimId: obs.claimId,
+          quote,
+          problem: `capture ${hash.slice(0, 12)} not found — evidence must stay resolvable`,
+        });
+        continue;
+      }
+      if (!normalizeForMatch(captureText).includes(normalizeForMatch(quote))) {
+        failures.push({
+          vendorId: obs.vendorId,
+          claimId: obs.claimId,
+          quote,
+          problem: `quote not found verbatim in capture ${hash.slice(0, 12)}`,
+        });
+      }
+    }
+  }
+  return failures;
+}
+
 // ---------------------------------------------------------------------------
 // Front states — deterministic, recomputed every time, never stored.