fullstackgtm 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.17.0] — 2026-06-11
+
+Market map classification: intensity readings become a one-command step, and
+the verbatim-quote rule becomes a mechanical gate instead of a prompt
+instruction.
+
+### Added
+
+- **`fullstackgtm market classify`** — LLM intensity readings for every
+  vendor × claim cell from the stored captures, through the same
+  bring-your-own-key constrained-tool-call seam as `call parse`
+  (provenance `extractor: "llm:<provider>:<model>"`). Vendors with no
+  usable captures score UNOBSERVABLE deterministically, without an LLM
+  call. `--vendor` classifies one vendor to `--out` for hand-merging;
+  `--model` overrides the provider default.
+- **Mechanical span verification** — because market sources are *stored*
+  captures (unlike transcripts, which pass through), every quoted evidence
+  span is checked character-for-character (whitespace-normalized) against
+  the capture it cites. Readings that fail bounce back to the model once
+  with the failures named; persistent failures abort with nothing stored.
+  The same gate now guards `market observe` (escape hatch: `--unverified`,
+  for sets whose captures genuinely live elsewhere) and the MCP submission
+  path — every proposal channel passes the same gate.
+- **`fullstackgtm market worksheet --vendor <id>`** — the no-key channel:
+  a self-contained packet (claims with judging definitions, surface rule,
+  captured page texts) for an agent or human to classify by hand and
+  submit via `observe`.
+- **`fullstackgtm market refresh`** — capture → classify → front drift →
+  HTML field report, one command. The weekly refresh is now a single
+  invocation (schedule it however you schedule things).
+- **MCP**: `fullstackgtm_market_worksheet` and `fullstackgtm_market_observe`
+  (validates + verifies + appends; returns the computed front states on
+  acceptance).
+- `forcedToolCall` exported from `llm.ts` — the one seam every LLM feature
+  in the package goes through.
+
 ## [0.16.0] — 2026-06-11
 
 The market map: a live model of the competitive category a company sells

package/dist/cli.js

@@ -18,7 +18,8 @@ import { auditReportToHtml, auditReportToMarkdown } from "./report.js";
 import { builtinAuditRules } from "./rules.js";
 import { sampleSnapshot } from "./sampleData.js";
 import { normalizeTranscript, parseCall, suggestCallDeal } from "./calls.js";
-import { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, loadMarketConfig, starterMarketConfig, validateObservationSet, } from "./market.js";
+import { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, loadCaptureTexts, loadMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, } from "./market.js";
+import { buildWorksheet, classifyMarket } from "./marketClassify.js";
 import { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
 import { DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
 import { resolveRecord } from "./resolve.js";
@@ -59,13 +60,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
@@ -617,9 +623,14 @@ async function requireLlmCredential(command = "parse") {
     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)";
+    const fallbackHint = 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}.`);
+        throw new Error(`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.");
     console.error(`Paste it once; it is validated and stored at ${credentialsPath()} (file mode 0600), like CRM logins.`);
@@ -729,9 +740,11 @@ function buildCallPlan(parsed, deal, proposed, current, extraNextSteps) {
 /**
  * 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) {
     const [subcommand, ...rest] = args;
@@ -740,9 +753,18 @@ async function marketCommand(args) {
         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,
@@ -785,10 +807,97 @@ 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 () => {
         const runLabel = option(rest, "--run");
         const set = runLabel ? await store.get(runLabel) : await store.latest();
@@ -838,7 +947,7 @@ 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)`);
 }
 /**
  * The resolve gate: exit 0 = safe to create, exit 2 = match found (exists or

package/dist/index.d.ts

@@ -19,7 +19,8 @@ export { extractCallInsights, normalizeTranscript, parseCall, parseTranscript, s
 export { sampleSnapshot } from "./sampleData.ts";
 export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, type CallScorecard, type LlmCredential, type LlmExtractedInsight, type LlmProvider, type Rubric, type ScoredDimension, } from "./llm.ts";
 export { resolveRecord, type ResolveCandidate, type ResolveMatch, type ResolveResult } from "./resolve.ts";
-export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadMarketConfig, marketHome, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, type CaptureEntry, type CaptureOptions, type ClaimFront, type ClaimIntensity, type FrontDrift, type FrontState, type MarketClaim, type MarketConfig, type MarketObservation, type MarketVendor, type ObservationConfidence, type ObservationSet, type ObservationStore, } from "./market.ts";
+export { captureMarket, computeFrontStates, 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 MarketClaim, type MarketConfig, type MarketObservation, type MarketVendor, 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 { ApprovalStatus, AuditFinding, AuditFindingSeverity, CanonicalAccount, CanonicalActivity, CanonicalContact, CanonicalDeal, CanonicalGtmSnapshot, CanonicalUser, CrmProvider, GtmAuditRule, GtmConnector, GtmEvidence, GtmEvidenceSourceSystem, GtmObjectType, GtmPolicy, GtmRuleContext, GtmRuleResult, GtmSnapshotIndex, PatchOperation, PatchOperationResult, PatchOperationType, PatchPlan, PatchPlanRun, PatchPlanRunStatus, PatchVerification, PipelineFinding, PipelineFindingStatus, PipelineFindingType, ProviderIdentity, RiskLevel, SourceFreshness, } from "./types.ts";

package/dist/index.js

@@ -19,6 +19,7 @@ export { extractCallInsights, normalizeTranscript, parseCall, parseTranscript, s
 export { sampleSnapshot } from "./sampleData.js";
 export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
 export { resolveRecord } from "./resolve.js";
-export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadMarketConfig, marketHome, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, } from "./market.js";
+export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadCaptureTexts, loadMarketConfig, marketHome, normalizeForMatch, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, } from "./market.js";
+export { buildWorksheet, classifyMarket, } from "./marketClassify.js";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
 export { suggestValues } from "./suggest.js";

package/dist/llm.d.ts

@@ -64,6 +64,13 @@ export declare function scoreCallLlm(transcript: string, rubric: Rubric, options
     title?: string;
 }): Promise<CallScorecard>;
 export declare function parseRubric(json: string): Rubric;
+/**
+ * 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 declare function forcedToolCall(prompt: string, toolName: string, schema: object, model: string, options: LlmCallOptions): Promise<unknown>;
 /** Cheap key validation against the provider's model-list endpoint. Status line only. */
 export declare function validateLlmKey(provider: LlmProvider, apiKey: string, fetchImpl?: typeof fetch): Promise<{
     ok: boolean;

package/dist/llm.js

@@ -158,7 +158,13 @@ export function parseRubric(json) {
     };
 }
 // ── Provider plumbing (raw fetch, forced tool calls) ───────────────────────
-async function forcedToolCall(prompt, toolName, schema, model, options) {
+/**
+ * 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, toolName, schema, model, options) {
     const fetchImpl = options.fetchImpl ?? fetch;
     if (options.provider === "anthropic") {
         const response = await llmFetch(fetchImpl, ANTHROPIC_URL, {

package/dist/market.d.ts

@@ -126,6 +126,25 @@ export declare function createFileObservationStore(category: string, directory?:
  * Returns problems; an empty array means accept.
  */
 export declare function validateObservationSet(config: MarketConfig, set: ObservationSet): string[];
+export declare function loadCaptureTexts(category: string, directory?: string): {
+    entries: CaptureEntry[];
+    textByHash: Map<string, string>;
+};
+/**
+ * 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 declare function normalizeForMatch(value: string): string;
+export type SpanVerificationFailure = {
+    vendorId: string;
+    claimId: string;
+    quote: string;
+    problem: string;
+};
+export declare function verifyEvidenceSpans(observations: MarketObservation[], textByHash: Map<string, string>): SpanVerificationFailure[];
 export type ClaimFront = {
     claimId: string;
     state: FrontState;

package/dist/market.js

@@ -270,6 +270,82 @@ export function validateObservationSet(config, set) {
     }
     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, directory) {
+    const dir = directory ?? join(marketHome(category), "captures");
+    const manifestPath = join(dir, "manifest.json");
+    const entries = existsSync(manifestPath)
+        ? JSON.parse(readFileSync(manifestPath, "utf8"))
+        : [];
+    const textByHash = new Map();
+    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) {
+    return value
+        .replace(/\s+([.,;:!?])/g, "$1")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function verifyEvidenceSpans(observations, textByHash) {
+    const failures = [];
+    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 rule v1: 0 loud → open (if anyone is quiet) or vacant; 1 loud →
  * owned; 2–3 loud → contested; ≥4 loud → saturated. Unobservable cells are

package/dist/marketClassify.d.ts

@@ -0,0 +1,49 @@
+import { type LlmCallOptions } from "./llm.ts";
+import { type CaptureEntry, type MarketClaim, type MarketConfig, type ObservationSet } from "./market.ts";
+export type ClassifyMarketOptions = {
+    llm: LlmCallOptions;
+    /** Observation run label to produce; must be new (the store is append-only). */
+    runLabel: string;
+    /** Capture run to classify; defaults to the most recent run in the manifest. */
+    captureRun?: string;
+    /** Restrict to these vendor ids (e.g. one new vendor); defaults to all. */
+    vendors?: string[];
+    /** Captures directory override (tests); defaults to the profile market home. */
+    capturesDir?: string;
+    now?: () => Date;
+};
+export type ClassifyMarketResult = {
+    set: ObservationSet;
+    model: string;
+    /** Cells where the model's quote failed mechanical verification and the retry fixed it. */
+    retriedVendorIds: string[];
+};
+export declare function classifyMarket(config: MarketConfig, options: ClassifyMarketOptions): Promise<ClassifyMarketResult>;
+/**
+ * The agent-driven alternative to LLM classification: a worksheet carrying
+ * everything needed to classify one vendor by hand or by an agent driving
+ * the CLI/MCP — claims with judging definitions, the surface rule, and the
+ * captured page texts. Submissions come back through `market observe`,
+ * which runs the same validation and span verification as `classify`.
+ */
+export type MarketWorksheet = {
+    category: string;
+    captureRun: string;
+    surfaceRule?: string;
+    vendor: {
+        id: string;
+        name: string;
+    };
+    claims: MarketClaim[];
+    pages: Array<{
+        kind: CaptureEntry["kind"];
+        url: string;
+        captureHash: string;
+        text: string;
+    }>;
+    instructions: string;
+};
+export declare function buildWorksheet(config: MarketConfig, vendorId: string, options?: {
+    captureRun?: string;
+    capturesDir?: string;
+}): MarketWorksheet;

package/dist/marketClassify.js

@@ -0,0 +1,201 @@
+import { DEFAULT_MODELS, forcedToolCall } from "./llm.js";
+import { loadCaptureTexts, observationId, verifyEvidenceSpans, } from "./market.js";
+/**
+ * LLM intensity classification for the market map — the same
+ * semi-deterministic posture as call extraction, with one upgrade calls
+ * can't have: because the source pages are stored captures, every quoted
+ * span is verified mechanically against the capture it cites before the
+ * observation is accepted. A reading whose quote isn't verbatim on the page
+ * bounces back to the model once with the failures named; if it still can't
+ * quote the page, classification fails rather than storing unverifiable
+ * evidence.
+ *
+ * Deterministic parts stay deterministic: vendors with no usable captures
+ * score UNOBSERVABLE on every claim without an LLM call, and front states
+ * downstream are computed from the store, never from model output.
+ */
+// Bound cost and context: a vendor's pages are classified in one call.
+const MAX_DOSSIER_CHARS = 48_000;
+const CLASSIFY_INSTRUCTIONS = `Classify this vendor's messaging intensity for EVERY claim listed.
+Rules:
+- Judge ONLY from the captured pages below. Do not use outside knowledge of the vendor.
+- intensity per the surface rule: "loud" = hero copy or a top-level-nav named product/program with a dedicated page; "quiet" = present on any page below that; "absent" = nowhere in the captures.
+- evidence quotes MUST be verbatim spans copied exactly from the captured text (≤300 chars). Every loud or quiet reading needs at least one quote. If you cannot quote it, the reading is absent.
+- An explicit disavowal ("we do not offer X", "call 988") is absent — put the disavowal quote in reason, it is informative signal.
+- url must be the page the quote came from, exactly as given in the page headers below.
+- reason: one reviewer-facing sentence.
+- Return a reading for every claim id. Never invent claim ids.`;
+const classifySchema = (claimIds) => ({
+    type: "object",
+    required: ["readings"],
+    properties: {
+        readings: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["claimId", "intensity", "confidence", "reason", "evidence"],
+                properties: {
+                    claimId: { type: "string", enum: claimIds },
+                    intensity: { type: "string", enum: ["loud", "quiet", "absent"] },
+                    confidence: { type: "string", enum: ["high", "medium", "low"] },
+                    reason: { type: "string", description: "One reviewer-facing sentence." },
+                    evidence: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            required: ["quote", "url"],
+                            properties: {
+                                quote: { type: "string", description: "VERBATIM span copied exactly from the captured page text. Never paraphrase." },
+                                url: { type: "string", description: "The page URL the quote came from, exactly as shown in the page header." },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+});
+function buildDossier(entries, textByHash) {
+    const pages = entries
+        .filter((entry) => entry.captureHash && textByHash.has(entry.captureHash))
+        .map((entry) => ({ entry, text: textByHash.get(entry.captureHash) }));
+    if (pages.length === 0)
+        return "";
+    const budget = Math.floor(MAX_DOSSIER_CHARS / pages.length);
+    return pages
+        .map(({ entry, text }) => {
+        const body = text.length <= budget
+            ? text
+            : `${text.slice(0, budget / 2)}\n[... middle of page truncated ...]\n${text.slice(-budget / 2)}`;
+        return `=== PAGE (${entry.kind}) ${entry.url} ===\n${body}`;
+    })
+        .join("\n\n");
+}
+function claimsBlock(claims) {
+    return claims
+        .map((claim) => `- ${claim.id}: ${claim.capability}\n  How to judge: ${claim.definition}`)
+        .join("\n");
+}
+export async function classifyMarket(config, options) {
+    const model = options.llm.model ?? DEFAULT_MODELS[options.llm.provider];
+    const { entries, textByHash } = loadCaptureTexts(config.category, options.capturesDir);
+    if (entries.length === 0) {
+        throw new Error(`No captures for ${config.category} — run \`market capture\` first`);
+    }
+    const captureRun = options.captureRun ?? entries[entries.length - 1].runLabel;
+    const runEntries = entries.filter((entry) => entry.runLabel === captureRun);
+    if (runEntries.length === 0) {
+        throw new Error(`No captures for run "${captureRun}" — available: ${[...new Set(entries.map((e) => e.runLabel))].join(", ")}`);
+    }
+    const observedAt = (options.now ?? (() => new Date()))().toISOString();
+    const vendorIds = options.vendors ?? config.vendors.map((vendor) => vendor.id);
+    const claimIds = config.claims.map((claim) => claim.id);
+    const observations = [];
+    const retriedVendorIds = [];
+    for (const vendorId of vendorIds) {
+        const vendor = config.vendors.find((candidate) => candidate.id === vendorId);
+        if (!vendor)
+            throw new Error(`Unknown vendor "${vendorId}"`);
+        const vendorEntries = runEntries.filter((entry) => entry.vendorId === vendorId);
+        const hashByUrl = new Map(vendorEntries.filter((entry) => entry.captureHash).map((entry) => [entry.url, entry.captureHash]));
+        const dossier = buildDossier(vendorEntries, textByHash);
+        if (!dossier) {
+            // Deterministic: no usable captures means UNOBSERVABLE everywhere — never
+            // ask a model to judge pages that were never read.
+            for (const claim of config.claims) {
+                observations.push({
+                    id: observationId(config.category, options.runLabel, vendorId, claim.id),
+                    vendorId,
+                    claimId: claim.id,
+                    observedAt,
+                    intensity: "unobservable",
+                    confidence: "high",
+                    reason: `No usable captures for ${vendor.name} in run ${captureRun} — cannot judge.`,
+                    evidence: [],
+                });
+            }
+            continue;
+        }
+        const prompt = (feedback) => `${CLASSIFY_INSTRUCTIONS}\n\nSurface rule for this category:\n${config.surfaceRule ?? "(default rule above)"}\n\nClaims to classify (all of them):\n${claimsBlock(config.claims)}\n${feedback}\nVendor: ${vendor.name}\nCaptured pages:\n${dossier}`;
+        const attempt = async (feedback) => {
+            const result = (await forcedToolCall(prompt(feedback), "classify_market_claims", classifySchema(claimIds), model, options.llm));
+            const readings = (result.readings ?? []).filter((reading) => claimIds.includes(reading.claimId));
+            const seen = new Set(readings.map((reading) => reading.claimId));
+            const problems = claimIds.filter((claimId) => !seen.has(claimId)).map((claimId) => `missing reading for ${claimId}`);
+            const candidate = readings.map((reading) => toObservation(reading, vendorId));
+            const failures = verifyEvidenceSpans(candidate, textByHash);
+            return { readings, problems, failures };
+        };
+        const toObservation = (reading, vendor) => ({
+            id: observationId(config.category, options.runLabel, vendor, reading.claimId),
+            vendorId: vendor,
+            claimId: reading.claimId,
+            observedAt,
+            intensity: reading.intensity,
+            confidence: reading.confidence,
+            reason: reading.reason,
+            evidence: (reading.evidence ?? []).map((item, index) => ({
+                id: `${observationId(config.category, options.runLabel, vendor, reading.claimId)}_ev${index}`,
+                sourceSystem: "web",
+                sourceObjectType: "page",
+                sourceObjectId: item.url,
+                text: item.quote,
+                observedAt,
+                metadata: { url: item.url, captureHash: hashByUrl.get(item.url) ?? "" },
+            })),
+        });
+        let outcome = await attempt("");
+        if (outcome.problems.length > 0 || outcome.failures.length > 0) {
+            retriedVendorIds.push(vendorId);
+            const failureLines = [
+                ...outcome.problems,
+                ...outcome.failures.map((failure) => `${failure.claimId}: ${failure.problem} (your quote: "${failure.quote.slice(0, 80)}")`),
+            ].join("\n- ");
+            outcome = await attempt(`\nYour previous answer had problems. Fix exactly these and answer again in full:\n- ${failureLines}\nQuotes must be copied character-for-character from the captured text.\n`);
+        }
+        if (outcome.problems.length > 0 || outcome.failures.length > 0) {
+            const detail = [...outcome.problems, ...outcome.failures.map((failure) => `${failure.claimId}: ${failure.problem}`)].slice(0, 10);
+            throw new Error(`Classification for ${vendor.name} failed mechanical verification after a retry:\n  ${detail.join("\n  ")}\nNothing was stored. Re-run, try another --model, or classify this vendor by hand via the worksheet.`);
+        }
+        for (const reading of outcome.readings)
+            observations.push(toObservation(reading, vendorId));
+    }
+    return {
+        set: {
+            id: `set_${config.category}_${options.runLabel}`,
+            category: config.category,
+            runLabel: options.runLabel,
+            runAt: observedAt,
+            extractor: `llm:${options.llm.provider}:${model}`,
+            observations,
+        },
+        model,
+        retriedVendorIds,
+    };
+}
+export function buildWorksheet(config, vendorId, options = {}) {
+    const vendor = config.vendors.find((candidate) => candidate.id === vendorId);
+    if (!vendor)
+        throw new Error(`Unknown vendor "${vendorId}"`);
+    const { entries, textByHash } = loadCaptureTexts(config.category, options.capturesDir);
+    const captureRun = options.captureRun ?? entries[entries.length - 1]?.runLabel;
+    if (!captureRun)
+        throw new Error(`No captures for ${config.category} — run \`market capture\` first`);
+    const pages = entries
+        .filter((entry) => entry.runLabel === captureRun && entry.vendorId === vendorId && entry.captureHash)
+        .map((entry) => ({
+        kind: entry.kind,
+        url: entry.url,
+        captureHash: entry.captureHash,
+        text: textByHash.get(entry.captureHash) ?? "",
+    }));
+    return {
+        category: config.category,
+        captureRun,
+        surfaceRule: config.surfaceRule,
+        vendor: { id: vendor.id, name: vendor.name },
+        claims: config.claims,
+        pages,
+        instructions: "Produce one observation per claim (intensity loud|quiet|absent from these pages only; unobservable only if a page you need failed to capture). Every loud/quiet reading must quote a verbatim span (≤300 chars) from a page's text, with that page's url and captureHash in evidence metadata. Submit as an ObservationSet via `market observe --from <file>` — quotes are mechanically verified against the captures.",
+    };
+}