fullstackgtm 0.16.0 → 0.17.0

package/dist/mcp.js

@@ -47,6 +47,8 @@ import { builtinAuditRules } from "./rules.js";
 import { sampleSnapshot } from "./sampleData.js";
 import { normalizeTranscript, parseCall } from "./calls.js";
 import { extractInsightsLlm, resolveLlmCredential } from "./llm.js";
+import { computeFrontStates, createFileObservationStore, loadCaptureTexts, loadMarketConfig, validateObservationSet, verifyEvidenceSpans, } from "./market.js";
+import { buildWorksheet } from "./marketClassify.js";
 import { resolveRecord } from "./resolve.js";
 import { suggestValues } from "./suggest.js";
 function content(value) {
@@ -244,6 +246,49 @@ export async function startMcpServer() {
         });
         return content(output === "markdown" ? formatPatchPlanRun(run) : run);
     });
+    server.registerTool("fullstackgtm_market_worksheet", {
+        title: "Market Map Classification Worksheet",
+        description: "Get everything needed to classify ONE vendor's messaging intensity for a market map: " +
+            "the claim taxonomy with judging definitions, the surface rule, and the captured page " +
+            "texts. Read each claim's definition, judge loud/quiet/absent from the page texts only, " +
+            "and quote verbatim spans (≤300 chars) for every loud/quiet reading. Submit the full " +
+            "ObservationSet via fullstackgtm_market_observe — quotes are verified character-for-" +
+            "character against the captures, so never paraphrase.",
+        inputSchema: {
+            vendorId: z.string(),
+            configPath: z.string().optional().describe("Path to market.config.json (default ./market.config.json)"),
+            captureRun: z.string().optional(),
+        },
+    }, async ({ vendorId, configPath, captureRun }) => {
+        const config = loadMarketConfig(resolve(process.cwd(), configPath ?? "market.config.json"));
+        return content(buildWorksheet(config, vendorId, { captureRun }));
+    });
+    server.registerTool("fullstackgtm_market_observe", {
+        title: "Submit Market Map Observations",
+        description: "Submit a complete ObservationSet (every vendor × claim cell) for a market map run. " +
+            "Validates coverage, the verbatim-evidence rule, and mechanically verifies every quoted " +
+            "span against the stored capture it cites. Returns problems if rejected; nothing is " +
+            "stored unless the whole set passes. Observations are append-only — use a new runLabel.",
+        inputSchema: {
+            observationsPath: z.string().describe("Path to the ObservationSet JSON file"),
+            configPath: z.string().optional().describe("Path to market.config.json (default ./market.config.json)"),
+        },
+    }, async ({ observationsPath, configPath }) => {
+        const config = loadMarketConfig(resolve(process.cwd(), configPath ?? "market.config.json"));
+        const set = JSON.parse(readFileSync(resolve(process.cwd(), observationsPath), "utf8"));
+        const problems = validateObservationSet(config, set);
+        const failures = verifyEvidenceSpans(set.observations, loadCaptureTexts(config.category).textByHash);
+        if (problems.length > 0 || failures.length > 0) {
+            return content({
+                accepted: false,
+                problems,
+                spanFailures: failures.map((failure) => `${failure.vendorId} × ${failure.claimId}: ${failure.problem}`),
+            });
+        }
+        await createFileObservationStore(config.category).append(set);
+        const fronts = computeFrontStates(config, set);
+        return content({ accepted: true, runLabel: set.runLabel, observations: set.observations.length, fronts });
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.16.0",
+  "version": "0.17.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,14 @@ import {
   computeFrontStates,
   createFileObservationStore,
   diffFrontStates,
+  loadCaptureTexts,
   loadMarketConfig,
   starterMarketConfig,
   validateObservationSet,
+  verifyEvidenceSpans,
   type ObservationSet,
 } from "./market.ts";
+import { buildWorksheet, classifyMarket } from "./marketClassify.ts";
 import { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 import {
   DEFAULT_RUBRIC,
@@ -107,13 +110,18 @@ 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 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 +704,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 +839,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 +853,18 @@ 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 report [--config <path>] [--run <label>] [--format md|html] [--out <path>]
+market refresh [--run <label>] [--model m]     capture → classify → fronts drift → HTML report
+
+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 +909,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 +1053,9 @@ recomputed deterministically on every invocation — never stored.`);
     return;
   }
 
-  throw new Error(`Unknown market subcommand: ${subcommand} (try: init, capture, observe, fronts, report)`);
+  throw new Error(
+    `Unknown market subcommand: ${subcommand} (try: init, capture, classify, worksheet, observe, fronts, report, refresh)`,
+  );
 }
 
 /**

package/src/index.ts

@@ -136,12 +136,15 @@ export {
   createFileObservationStore,
   diffFrontStates,
   extractReadableText,
+  loadCaptureTexts,
   loadMarketConfig,
   marketHome,
+  normalizeForMatch,
   observationId,
   parseMarketConfig,
   starterMarketConfig,
   validateObservationSet,
+  verifyEvidenceSpans,
   type CaptureEntry,
   type CaptureOptions,
   type ClaimFront,
@@ -155,7 +158,15 @@ export {
   type ObservationConfidence,
   type ObservationSet,
   type ObservationStore,
+  type SpanVerificationFailure,
 } from "./market.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

@@ -408,6 +408,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.