fullstackgtm 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md).
 
+## [0.20.0] — 2026-06-12
+
+The directive layer: the market map joined to your own CRM ground truth.
+Two companies mapping the same category see the same fronts; their own
+conversion fingerprints produce different directives.
+
+### Added
+
+- **`fullstackgtm market overlay`** — joins the observation store to a CRM
+  snapshot and a call corpus, and emits OCCUPY / PROMOTE / URGENT / RETREAT
+  directives. Deterministic throughout: claim mentions are word-boundary
+  matches of each claim's configured `terms` (and vendor `aliases`) against
+  call documents (`call parse` output, optionally deal-linked via a manifest);
+  every directive carries ≥1 observation id and ≥1 CRM statistic **with its
+  sample size**; explicit minimum-evidence thresholds (`--min-mentions`,
+  `--promote-lift`) refuse to mint strategy from small samples — and an
+  empty directive list is reported as an answer, not a failure.
+  - OCCUPY: open front the anchor doesn't own, buyers demonstrably discuss it.
+  - PROMOTE: anchor-quiet claim whose mentioned-deal win rate beats baseline.
+  - URGENT: a front the anchor is loud on drifted toward saturation
+    (`--prior-run`).
+  - RETREAT: saturated front, loud anchor, zero presence in won-deal calls.
+  - `--save --task-account <id>|--task-deal <id>` turns directives into
+    approval-gated `create_task` operations through the normal
+    plans → approve → apply gate. Nothing writes without approval.
+- **`fullstackgtm market scale` + scale-sized report bubbles** — vendors may
+  carry `scaleSignals` (citable G2 review counts, LinkedIn headcount,
+  disclosed revenue, self-reported customers — each with sourceUrl, verbatim
+  quote, asOf, and caveat). A deterministic composite (log-normalized
+  per metric within the set, mean over available metrics, singleton metrics
+  skipped) yields a **relative scale index — never "market share"
+  unqualified** — and the strategic map's dot area becomes proportional to
+  it when every placeable vendor has signals (LOUD-count sizing otherwise;
+  the caption always states which, and bubbles are now area-proportional
+  either way).
+- `MarketClaim.terms` and `MarketVendor.aliases` for deterministic mention
+  matching; `MarketVendor.scaleSignals`.
+
 ## [0.19.0] — 2026-06-11
 
 Governed bulk writes, plus fixes from the 0.18 published-artifact verification.

package/dist/cli.js

@@ -20,6 +20,8 @@ import { sampleSnapshot } from "./sampleData.js";
 import { normalizeTranscript, parseCall, suggestCallDeal } from "./calls.js";
 import { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, loadCaptureTexts, loadMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, } from "./market.js";
 import { assessAxes, axesReportToText } from "./marketAxes.js";
+import { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, } from "./marketOverlay.js";
+import { computeScaleIndex, scaleReportToText } from "./marketScale.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";
@@ -68,6 +70,8 @@ Usage:
   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 overlay --snapshot <crm.json> [--calls <files>] [--save]
+  fullstackgtm market scale [--json]
   fullstackgtm market refresh [--run <label>] [--model m]
                                                the live competitive map: capture vendor pages (content-addressed),
                                                classify intensity per claim (LLM bring-your-own-key, or fill the
@@ -775,9 +779,24 @@ 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 overlay --snapshot <crm.json> [--calls <parsed.json|manifest.json>]... [--prior-run <label>]
+               [--min-mentions N] [--promote-lift X] [--json] [--save --task-account <id>|--task-deal <id>]
+market scale [--config <path>] [--json]
 market report [--config <path>] [--run <label>] [--format md|html] [--out <path>]
 market refresh [--run <label>] [--model m]     capture → classify → fronts drift → HTML report
 
+overlay is the directive layer: joins the map to YOUR CRM ground truth and
+emits OCCUPY / PROMOTE / URGENT / RETREAT directives, each carrying ≥1
+observation and ≥1 CRM statistic with its sample size. Claim mentions are
+deterministic word-boundary matches of each claim's "terms" against call
+documents (call parse output); small samples refuse to become strategy
+(--min-mentions, default 3). --save turns directives into approval-gated
+create_task operations through the normal plans → approve → apply gate.
+
+scale prints the relative scale index that sizes the report's bubbles when
+vendors carry scaleSignals (citable review counts / headcount / revenue —
+a within-set index, never "market share" unqualified).
+
 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
@@ -982,7 +1001,76 @@ recomputed deterministically on every invocation — never stored.`);
         console.log(axesReportToText(report));
         return;
     }
-    throw new Error(`Unknown market subcommand: ${subcommand} (try: init, capture, classify, worksheet, observe, fronts, axes, report, refresh)`);
+    if (subcommand === "scale") {
+        const report = computeScaleIndex(config);
+        if (rest.includes("--json")) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        console.log(scaleReportToText(config, report));
+        return;
+    }
+    if (subcommand === "overlay") {
+        const set = await loadSet();
+        const snapshotPath = option(rest, "--snapshot");
+        if (!snapshotPath) {
+            throw new Error("market overlay requires --snapshot <canonical-snapshot.json> (fullstackgtm snapshot --out it first) — directives need CRM ground truth");
+        }
+        const snapshot = JSON.parse(readFileSync(resolve(process.cwd(), snapshotPath), "utf8"));
+        // --calls accepts ParsedCall JSON files (from `call parse --out`) and/or
+        // manifest arrays [{path, dealId?}] linking calls to deals. Repeatable.
+        const documents = [];
+        const addParsedCall = (parsedPath, dealId) => {
+            const parsed = JSON.parse(readFileSync(resolve(process.cwd(), parsedPath), "utf8"));
+            const text = [
+                ...(parsed.segments ?? []).map((segment) => segment.text ?? ""),
+                ...(parsed.insights ?? []).map((insight) => `${insight.text ?? ""} ${insight.evidence ?? ""}`),
+            ].join("\n");
+            documents.push({ id: parsed.id ?? parsedPath, text, dealId, occurredAt: parsed.evidence?.[0]?.capturedAt });
+        };
+        for (let i = 0; i < rest.length; i += 1) {
+            if (rest[i] !== "--calls")
+                continue;
+            const callsPath = rest[i + 1];
+            if (!callsPath)
+                throw new Error("--calls needs a path");
+            const raw = JSON.parse(readFileSync(resolve(process.cwd(), callsPath), "utf8"));
+            if (Array.isArray(raw)) {
+                for (const entry of raw)
+                    addParsedCall(entry.path, entry.dealId);
+            }
+            else {
+                addParsedCall(callsPath);
+            }
+        }
+        const priorLabel = option(rest, "--prior-run");
+        const priorSet = priorLabel ? await store.get(priorLabel) : null;
+        if (priorLabel && !priorSet)
+            throw new Error(`No observation run "${priorLabel}" for URGENT drift`);
+        const stats = computeOverlayStats(config, snapshot, documents);
+        const directives = computeDirectives(config, set, stats, {
+            minMentions: numericOption(rest, "--min-mentions") ?? undefined,
+            promoteLift: numericOption(rest, "--promote-lift") ?? undefined,
+            priorSet: priorSet ?? undefined,
+        });
+        if (rest.includes("--json")) {
+            console.log(JSON.stringify({ stats, directives }, null, 2));
+            return;
+        }
+        console.log(overlayToMarkdown(stats, directives));
+        if (rest.includes("--save")) {
+            const taskAccount = option(rest, "--task-account");
+            const taskDeal = option(rest, "--task-deal");
+            if (!taskAccount && !taskDeal) {
+                throw new Error("--save needs --task-account <id> or --task-deal <id>: directives become approval-gated create_task operations, and the CRM needs a record to hang them on (your own company's account record works well)");
+            }
+            const plan = directivesToPlan(config, set, directives, taskDeal ? { objectType: "deal", objectId: taskDeal } : { objectType: "account", objectId: taskAccount });
+            const stored = await createFilePlanStore().save(plan);
+            console.log(`Saved plan ${stored.plan.id} (${directives.length} directive task(s); approve via \`plans approve\`)`);
+        }
+        return;
+    }
+    throw new Error(`Unknown market subcommand: ${subcommand} (try: init, capture, classify, worksheet, observe, fronts, axes, overlay, scale, report, refresh)`);
 }
 /**
  * The resolve gate: exit 0 = safe to create, exit 2 = match found (exists or

package/dist/index.d.ts

@@ -20,9 +20,11 @@ export { extractCallInsights, normalizeTranscript, parseCall, parseTranscript, s
 export { sampleSnapshot } from "./sampleData.ts";
 export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, forcedToolCall, 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, 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, type MarketVendor, type ObservationConfidence, type ObservationSet, type ObservationStore, type SpanVerificationFailure, } 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 MarketAxis, type MarketClaim, type MarketConfig, type MarketObservation, type MarketVendor, type ObservationConfidence, type ObservationSet, type ObservationStore, type ScaleSignal, 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 { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, type CallDocument, type ClaimMentionStats, type DirectiveStat, type DirectiveType, type MarketDirective, type OverlayOptions, type OverlayStats, type VendorMentionStats, } from "./marketOverlay.ts";
+export { computeScaleIndex, scaleReportToText, type ScaleReport, type VendorScale } from "./marketScale.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

@@ -23,5 +23,7 @@ export { resolveRecord } from "./resolve.js";
 export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadCaptureTexts, loadMarketConfig, marketHome, normalizeForMatch, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, } from "./market.js";
 export { assessAxes, axesReportToText, axisPosition, messageBreadth, pcaTop2, pearson, } from "./marketAxes.js";
 export { buildWorksheet, classifyMarket, } from "./marketClassify.js";
+export { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, } from "./marketOverlay.js";
+export { computeScaleIndex, scaleReportToText } from "./marketScale.js";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
 export { suggestValues } from "./suggest.js";

package/dist/market.d.ts

@@ -29,6 +29,30 @@ export type MarketClaim = {
     pricingStructure: string;
     /** Operational definition: how a reader judges LOUD vs QUIET vs ABSENT. */
     definition: string;
+    /**
+     * Exact terms buyers use for this claim, for deterministic mention
+     * matching against call transcripts (the overlay). No terms = no mention
+     * stats for this claim; matching is word-boundary, case-insensitive.
+     */
+    terms?: string[];
+};
+/**
+ * One public, citable scale signal for a vendor (G2 review count, LinkedIn
+ * headcount, disclosed revenue, self-reported customer count). The composite
+ * of several biased-in-different-directions signals sizes the report's
+ * bubbles — a RELATIVE scale index within the mapped set, never "market
+ * share" unqualified.
+ */
+export type ScaleSignal = {
+    /** e.g. "g2_reviews", "linkedin_employees", "revenue_usd", "self_reported_customers". */
+    metric: string;
+    value: number;
+    unit: string;
+    sourceUrl: string;
+    /** Verbatim snippet containing the number — same evidence posture as observations. */
+    quote: string;
+    asOf: string;
+    caveat?: string;
 };
 export type MarketVendor = {
     id: string;
@@ -39,6 +63,10 @@ export type MarketVendor = {
         pricing: string | null;
         product: string[];
     };
+    /** Alternate names/spellings for deterministic mention matching. */
+    aliases?: string[];
+    /** Public scale signals; see ScaleSignal. */
+    scaleSignals?: ScaleSignal[];
     notes?: string;
 };
 export type MarketAxis = {

package/dist/marketOverlay.d.ts

@@ -0,0 +1,116 @@
+import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
+import type { MarketConfig, ObservationSet } from "./market.ts";
+/**
+ * The directive layer: the market map joined to the company's own ground
+ * truth. The map alone says what the category looks like; the overlay says
+ * what THIS company should do about it — and two companies running the same
+ * map see different directives, because the overlay is their own conversion
+ * fingerprint.
+ *
+ * Everything here is deterministic. Inputs are the observation store (front
+ * states), a CRM snapshot (won/lost deals), and call documents (transcript
+ * text, optionally linked to deals). Claim mentions are found by exact
+ * word-boundary term matching against each claim's configured `terms` —
+ * the same posture as the rest of the map: no model in the loop, every
+ * directive carries at least one observation and at least one CRM statistic
+ * with its sample size, and small samples refuse to become claims (the
+ * minimum-evidence thresholds are explicit options, not vibes).
+ */
+export type CallDocument = {
+    id: string;
+    text: string;
+    /** Links the document to a deal for win/loss statistics; optional. */
+    dealId?: string;
+    occurredAt?: string;
+};
+export type ClaimMentionStats = {
+    claimId: string;
+    /** Documents whose text matches any of the claim's terms. */
+    mentionDocIds: string[];
+    /** Distinct deals among those documents (only docs with dealId count). */
+    mentionDealIds: string[];
+    wonDeals: number;
+    lostDeals: number;
+    /** won / (won + lost) among closed mentioned deals; null below any closure. */
+    winRateWhenMentioned: number | null;
+};
+export type VendorMentionStats = {
+    vendorId: string;
+    mentionDocIds: string[];
+    mentionDealIds: string[];
+    wonWhenMentioned: number;
+    lostWhenMentioned: number;
+};
+export type OverlayStats = {
+    documents: number;
+    documentsWithDeal: number;
+    deals: {
+        total: number;
+        closed: number;
+        won: number;
+        baselineWinRate: number | null;
+    };
+    claims: ClaimMentionStats[];
+    vendors: VendorMentionStats[];
+};
+export type DirectiveType = "occupy" | "promote" | "urgent" | "retreat";
+export type DirectiveStat = {
+    name: string;
+    value: number | string;
+    n: number;
+};
+export type MarketDirective = {
+    id: string;
+    type: DirectiveType;
+    claimId: string;
+    title: string;
+    summary: string;
+    recommendation: string;
+    /** ≥1 observation id and ≥1 CRM stat — the spec's evidence-chain rule. */
+    observationIds: string[];
+    stats: DirectiveStat[];
+};
+export type OverlayOptions = {
+    /** Minimum mention documents before OCCUPY/PROMOTE may fire (default 3). */
+    minMentions?: number;
+    /** Minimum win-rate lift over baseline for PROMOTE (default 0.10). */
+    promoteLift?: number;
+    /** Minimum won deals in the corpus before RETREAT may fire (default 3). */
+    minWonDealsForRetreat?: number;
+    /** Prior run's observations: enables URGENT (front drift) directives. */
+    priorSet?: ObservationSet;
+};
+/**
+ * Deterministic claim/vendor mention statistics over a call corpus.
+ * Claims match on their configured `terms` (claims without terms simply have
+ * no mention stats — the directives that need mentions will not fire for
+ * them); vendors match on name + configured `aliases`.
+ */
+export declare function computeOverlayStats(config: MarketConfig, snapshot: CanonicalGtmSnapshot, documents: CallDocument[]): OverlayStats;
+/**
+ * Directive rules v1 — deterministic over (front states × overlay stats),
+ * with explicit minimum-evidence thresholds so small samples cannot mint
+ * strategy. Requires config.anchorVendor: directives are advice to someone.
+ *
+ *   OCCUPY  — open/vacant front the anchor doesn't own loudly, and buyers
+ *             demonstrably talk about it (≥ minMentions documents).
+ *   PROMOTE — anchor is quiet on a claim whose mentioned-deal win rate beats
+ *             baseline by ≥ promoteLift (with ≥ minMentions mentioned deals).
+ *   URGENT  — a front the anchor is loud on drifted toward saturation since
+ *             the prior run (requires priorSet).
+ *   RETREAT — saturated front the anchor is loud on, with zero presence in
+ *             won-deal conversations despite a corpus that contains wins.
+ */
+export declare function computeDirectives(config: MarketConfig, set: ObservationSet, stats: OverlayStats, options?: OverlayOptions): MarketDirective[];
+/**
+ * Emit directives as a standard dry-run patch plan: one approval-gated
+ * create_task per directive against a designated CRM record (the company's
+ * own account/deal record — directives are strategy tasks, and the CRM
+ * needs somewhere to hang them). Approving and applying goes through the
+ * normal plans → approve → apply gate; nothing here writes.
+ */
+export declare function directivesToPlan(config: MarketConfig, set: ObservationSet, directives: MarketDirective[], target: {
+    objectType: "account" | "deal";
+    objectId: string;
+}, now?: () => Date): PatchPlan;
+export declare function overlayToMarkdown(stats: OverlayStats, directives: MarketDirective[]): string;

package/dist/marketOverlay.js

@@ -0,0 +1,258 @@
+import { computeFrontStates, diffFrontStates } from "./market.js";
+function fnv1a(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i += 1) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function termPattern(terms) {
+    const cleaned = terms.map((term) => term.trim()).filter(Boolean);
+    if (cleaned.length === 0)
+        return null;
+    const escaped = cleaned.map((term) => term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\s+/g, "\\s+"));
+    return new RegExp(`\\b(?:${escaped.join("|")})\\b`, "i");
+}
+/**
+ * Deterministic claim/vendor mention statistics over a call corpus.
+ * Claims match on their configured `terms` (claims without terms simply have
+ * no mention stats — the directives that need mentions will not fire for
+ * them); vendors match on name + configured `aliases`.
+ */
+export function computeOverlayStats(config, snapshot, documents) {
+    const dealById = new Map(snapshot.deals.map((deal) => [deal.id, deal]));
+    const closed = snapshot.deals.filter((deal) => deal.isClosed === true);
+    const won = closed.filter((deal) => deal.isWon === true);
+    const baselineWinRate = closed.length > 0 ? won.length / closed.length : null;
+    const dealOutcome = (dealIds) => {
+        let wonCount = 0;
+        let lostCount = 0;
+        for (const dealId of dealIds) {
+            const deal = dealById.get(dealId);
+            if (!deal || deal.isClosed !== true)
+                continue;
+            if (deal.isWon === true)
+                wonCount += 1;
+            else
+                lostCount += 1;
+        }
+        return { wonCount, lostCount };
+    };
+    const claims = config.claims.map((claim) => {
+        const pattern = termPattern(claim.terms ?? []);
+        const mentionDocs = pattern ? documents.filter((doc) => pattern.test(doc.text)) : [];
+        const mentionDealIds = [...new Set(mentionDocs.map((doc) => doc.dealId).filter((id) => !!id))];
+        const { wonCount, lostCount } = dealOutcome(mentionDealIds);
+        return {
+            claimId: claim.id,
+            mentionDocIds: mentionDocs.map((doc) => doc.id),
+            mentionDealIds,
+            wonDeals: wonCount,
+            lostDeals: lostCount,
+            winRateWhenMentioned: wonCount + lostCount > 0 ? wonCount / (wonCount + lostCount) : null,
+        };
+    });
+    const vendors = config.vendors.map((vendor) => {
+        const pattern = termPattern([vendor.name, ...(vendor.aliases ?? [])]);
+        const mentionDocs = pattern ? documents.filter((doc) => pattern.test(doc.text)) : [];
+        const mentionDealIds = [...new Set(mentionDocs.map((doc) => doc.dealId).filter((id) => !!id))];
+        const { wonCount, lostCount } = dealOutcome(mentionDealIds);
+        return {
+            vendorId: vendor.id,
+            mentionDocIds: mentionDocs.map((doc) => doc.id),
+            mentionDealIds,
+            wonWhenMentioned: wonCount,
+            lostWhenMentioned: lostCount,
+        };
+    });
+    return {
+        documents: documents.length,
+        documentsWithDeal: documents.filter((doc) => doc.dealId).length,
+        deals: { total: snapshot.deals.length, closed: closed.length, won: won.length, baselineWinRate },
+        claims,
+        vendors,
+    };
+}
+/**
+ * Directive rules v1 — deterministic over (front states × overlay stats),
+ * with explicit minimum-evidence thresholds so small samples cannot mint
+ * strategy. Requires config.anchorVendor: directives are advice to someone.
+ *
+ *   OCCUPY  — open/vacant front the anchor doesn't own loudly, and buyers
+ *             demonstrably talk about it (≥ minMentions documents).
+ *   PROMOTE — anchor is quiet on a claim whose mentioned-deal win rate beats
+ *             baseline by ≥ promoteLift (with ≥ minMentions mentioned deals).
+ *   URGENT  — a front the anchor is loud on drifted toward saturation since
+ *             the prior run (requires priorSet).
+ *   RETREAT — saturated front the anchor is loud on, with zero presence in
+ *             won-deal conversations despite a corpus that contains wins.
+ */
+export function computeDirectives(config, set, stats, options = {}) {
+    const anchor = config.anchorVendor;
+    if (!anchor)
+        throw new Error("market overlay requires anchorVendor in the config — directives are advice to someone");
+    const minMentions = options.minMentions ?? 3;
+    const promoteLift = options.promoteLift ?? 0.1;
+    const minWonDealsForRetreat = options.minWonDealsForRetreat ?? 3;
+    const fronts = computeFrontStates(config, set);
+    const frontByClaim = new Map(fronts.map((front) => [front.claimId, front]));
+    const statsByClaim = new Map(stats.claims.map((claim) => [claim.claimId, claim]));
+    const anchorIntensity = new Map();
+    const loudObservationIds = new Map();
+    for (const obs of set.observations) {
+        if (obs.vendorId === anchor)
+            anchorIntensity.set(obs.claimId, { intensity: obs.intensity, observationId: obs.id });
+        if (obs.intensity === "loud") {
+            const ids = loudObservationIds.get(obs.claimId) ?? [];
+            ids.push(obs.id);
+            loudObservationIds.set(obs.claimId, ids);
+        }
+    }
+    const directives = [];
+    const claimName = new Map(config.claims.map((claim) => [claim.id, claim.capability.split(":")[0]]));
+    const push = (type, claimId, summary, recommendation, observationIds, statsList) => {
+        directives.push({
+            id: `dir_${fnv1a(`${config.category}|${set.runLabel}|${type}|${claimId}`)}`,
+            type,
+            claimId,
+            title: `${type.toUpperCase()}: ${claimName.get(claimId) ?? claimId}`,
+            summary,
+            recommendation,
+            observationIds: [...new Set(observationIds)].filter(Boolean),
+            stats: statsList,
+        });
+    };
+    for (const claim of config.claims) {
+        const front = frontByClaim.get(claim.id);
+        const mention = statsByClaim.get(claim.id);
+        const anchorObs = anchorIntensity.get(claim.id);
+        if (!front || !anchorObs)
+            continue;
+        if ((front.state === "open" || front.state === "vacant") &&
+            (anchorObs.intensity === "absent" || anchorObs.intensity === "quiet") &&
+            mention &&
+            mention.mentionDocIds.length >= minMentions) {
+            push("occupy", claim.id, `No vendor is loud on this claim, and it came up in ${mention.mentionDocIds.length} of ${stats.documents} call documents.`, `Claim it: buyers already talk about this and nobody owns the message. Anchor is currently ${anchorObs.intensity}.`, [anchorObs.observationId], [
+                { name: "mention_documents", value: mention.mentionDocIds.length, n: stats.documents },
+                { name: "front_state", value: front.state, n: config.vendors.length },
+            ]);
+        }
+        if (anchorObs.intensity === "quiet" &&
+            mention &&
+            mention.winRateWhenMentioned !== null &&
+            stats.deals.baselineWinRate !== null &&
+            mention.wonDeals + mention.lostDeals >= minMentions &&
+            mention.winRateWhenMentioned >= stats.deals.baselineWinRate + promoteLift) {
+            push("promote", claim.id, `Anchor ships this quietly; deals where it comes up close at ${(mention.winRateWhenMentioned * 100).toFixed(0)}% vs ${(stats.deals.baselineWinRate * 100).toFixed(0)}% baseline.`, "Turn it loud: the conversion fingerprint says this claim wins deals when discussed.", [anchorObs.observationId], [
+                { name: "win_rate_when_mentioned", value: Number(mention.winRateWhenMentioned.toFixed(3)), n: mention.wonDeals + mention.lostDeals },
+                { name: "baseline_win_rate", value: Number(stats.deals.baselineWinRate.toFixed(3)), n: stats.deals.closed },
+            ]);
+        }
+        if (front.state === "saturated" &&
+            anchorObs.intensity === "loud" &&
+            mention &&
+            stats.deals.won >= minWonDealsForRetreat &&
+            stats.documentsWithDeal > 0 &&
+            mention.wonDeals === 0) {
+            push("retreat", claim.id, `${front.loudVendorIds.length} vendors shout this claim; it appears in zero of the anchor's won-deal conversations (${stats.deals.won} won deals in corpus).`, "Stop spending message budget on a saturated front that never shows up in wins.", [anchorObs.observationId, ...(loudObservationIds.get(claim.id) ?? [])], [
+                { name: "won_deals_mentioning", value: 0, n: stats.deals.won },
+                { name: "loud_vendors", value: front.loudVendorIds.length, n: config.vendors.length },
+            ]);
+        }
+    }
+    if (options.priorSet) {
+        const drift = diffFrontStates(computeFrontStates(config, options.priorSet), fronts);
+        const toward = (before, after) => {
+            const order = ["vacant", "open", "owned", "contested", "saturated"];
+            return order.indexOf(after) > order.indexOf(before);
+        };
+        for (const change of drift) {
+            const anchorObs = anchorIntensity.get(change.claimId);
+            if (!anchorObs || anchorObs.intensity !== "loud" || !toward(change.before, change.after))
+                continue;
+            const mention = statsByClaim.get(change.claimId);
+            push("urgent", change.claimId, `Front moved ${change.before} → ${change.after} since ${options.priorSet.runLabel} on a claim the anchor is loud on.`, "The window is closing: decide whether to defend (differentiate the claim) or bank the position before it saturates.", [anchorObs.observationId], [
+                { name: "front_drift", value: `${change.before}→${change.after}`, n: config.vendors.length },
+                { name: "mention_documents", value: mention?.mentionDocIds.length ?? 0, n: stats.documents },
+            ]);
+        }
+    }
+    return directives.sort((a, b) => a.type.localeCompare(b.type) || a.claimId.localeCompare(b.claimId));
+}
+/**
+ * Emit directives as a standard dry-run patch plan: one approval-gated
+ * create_task per directive against a designated CRM record (the company's
+ * own account/deal record — directives are strategy tasks, and the CRM
+ * needs somewhere to hang them). Approving and applying goes through the
+ * normal plans → approve → apply gate; nothing here writes.
+ */
+export function directivesToPlan(config, set, directives, target, now = () => new Date()) {
+    const createdAt = now().toISOString();
+    const findings = directives.map((directive) => ({
+        id: `find_${fnv1a(directive.id)}`,
+        objectType: target.objectType,
+        objectId: target.objectId,
+        ruleId: `market_directive_${directive.type}`,
+        title: directive.title,
+        severity: directive.type === "urgent" ? "critical" : "warning",
+        summary: directive.summary,
+        recommendation: directive.recommendation,
+        evidenceIds: directive.observationIds,
+    }));
+    const evidence = directives.map((directive) => ({
+        id: `ev_${fnv1a(directive.id)}`,
+        sourceSystem: "web",
+        sourceObjectType: "market_map",
+        sourceObjectId: `${config.category}/${set.runLabel}`,
+        title: directive.title,
+        text: `${directive.summary} Stats: ${directive.stats.map((stat) => `${stat.name}=${stat.value} (n=${stat.n})`).join("; ")}`,
+        observedAt: set.runAt,
+        metadata: { observationIds: directive.observationIds, stats: directive.stats },
+    }));
+    const operations = directives.map((directive) => ({
+        id: `op_${fnv1a(directive.id)}`,
+        objectType: target.objectType,
+        objectId: target.objectId,
+        operation: "create_task",
+        field: "task",
+        afterValue: `${directive.title} — ${directive.recommendation} (${directive.stats.map((stat) => `${stat.name}=${stat.value}, n=${stat.n}`).join("; ")})`,
+        reason: directive.summary,
+        riskLevel: "low",
+        approvalRequired: true,
+        sourceRuleOrPolicy: `market_directive_${directive.type}`,
+        evidenceIds: [`ev_${fnv1a(directive.id)}`],
+    }));
+    return {
+        id: `patch_plan_market_${fnv1a(`${config.category}|${set.runLabel}|${createdAt}`)}`,
+        title: `Market directives — ${config.category} (${set.runLabel})`,
+        createdAt,
+        status: "needs_approval",
+        dryRun: true,
+        summary: `${directives.length} directive(s) from the ${config.category} market map joined to CRM ground truth.`,
+        findings,
+        evidence,
+        operations,
+    };
+}
+export function overlayToMarkdown(stats, directives) {
+    const lines = [];
+    lines.push(`Corpus: ${stats.documents} documents (${stats.documentsWithDeal} deal-linked) · ` +
+        `${stats.deals.closed} closed deals, ${stats.deals.won} won` +
+        (stats.deals.baselineWinRate !== null ? ` (baseline ${(stats.deals.baselineWinRate * 100).toFixed(0)}%)` : ""));
+    lines.push("");
+    if (directives.length === 0) {
+        lines.push("No directives met the evidence thresholds. That is an answer, not a failure:");
+        lines.push("either the corpus is too thin (add calls), or the current position needs no move.");
+    }
+    for (const directive of directives) {
+        lines.push(`## ${directive.title}`);
+        lines.push(directive.summary);
+        lines.push(`→ ${directive.recommendation}`);
+        lines.push(`evidence: ${directive.observationIds.length} observation(s) · ${directive.stats
+            .map((stat) => `${stat.name}=${stat.value} (n=${stat.n})`)
+            .join(" · ")}`);
+        lines.push("");
+    }
+    return `${lines.join("\n")}\n`;
+}