@sanity/ailf 5.0.0 → 6.1.0

package/dist/_vendor/ailf-core/services/diagnosis/cards/top-recommendations.d.ts

@@ -0,0 +1,41 @@
+/**
+ * top-recommendations card — LLM-driven actionable suggestion generator.
+ *
+ * Model: claude-opus-4-6 (high-stakes per AI-SPEC §4 model routing)
+ * Version: top-recommendations@0.1.0
+ *
+ * Mitigations:
+ * - failure-mode #2: few-shot examples in system prompt; body ≥40 chars
+ * - failure-mode #5: docSlug refined against report manifest allow-list
+ *
+ * Schema is in the D0045 trust-boundary scan root; `satisfies` clause is
+ * mandatory (cards/ is a SCAN_ROOT in check-trust-boundary-satisfies.ts).
+ *
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-AI-SPEC.md §3
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-AI-SPEC.md §4
+ */
+import { z } from "zod";
+import type { CardGenerator } from "../../diagnosis-runner.js";
+/**
+ * Module-level schema: static shape check only.
+ * Per-call: an additive `.refine()` over the allow-list (built inside the
+ * generator so it closes over the runtime `report`).
+ *
+ * AI-SPEC §3 Pitfall 1: per-call schemas are LOCAL to the generator,
+ * NOT at module scope.
+ */
+export declare const TopRecommendationsBodySchema: z.ZodObject<{
+    summary: z.ZodString;
+    suggestions: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        body: z.ZodString;
+        priority: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
+        docSlug: z.ZodString;
+        sectionHeading: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const generateTopRecommendations: CardGenerator;

package/dist/_vendor/ailf-core/services/diagnosis/cards/top-recommendations.js

@@ -0,0 +1,111 @@
+/**
+ * top-recommendations card — LLM-driven actionable suggestion generator.
+ *
+ * Model: claude-opus-4-6 (high-stakes per AI-SPEC §4 model routing)
+ * Version: top-recommendations@0.1.0
+ *
+ * Mitigations:
+ * - failure-mode #2: few-shot examples in system prompt; body ≥40 chars
+ * - failure-mode #5: docSlug refined against report manifest allow-list
+ *
+ * Schema is in the D0045 trust-boundary scan root; `satisfies` clause is
+ * mandatory (cards/ is a SCAN_ROOT in check-trust-boundary-satisfies.ts).
+ *
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-AI-SPEC.md §3
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-AI-SPEC.md §4
+ */
+import { z } from "zod";
+import { modelId as mkModelId } from "../../../ports/llm-client.js";
+import { buildTopRecommendationsPrompt, buildDocSlugAllowList, } from "../prompt-builders.js";
+// ---------------------------------------------------------------------------
+// Body schema (D0045 trust boundary — satisfies required)
+// ---------------------------------------------------------------------------
+/**
+ * Module-level schema: static shape check only.
+ * Per-call: an additive `.refine()` over the allow-list (built inside the
+ * generator so it closes over the runtime `report`).
+ *
+ * AI-SPEC §3 Pitfall 1: per-call schemas are LOCAL to the generator,
+ * NOT at module scope.
+ */
+export const TopRecommendationsBodySchema = z.object({
+    summary: z.string().min(1).max(500),
+    suggestions: z
+        .array(z.object({
+        title: z.string().min(1).max(200),
+        body: z
+            .string()
+            .min(40, "suggestion.body must be ≥40 characters")
+            .refine((b) => /`[^`]+`/.test(b), "suggestion.body must contain at least one backtick-delimited artifact"),
+        priority: z.enum(["high", "medium", "low"]),
+        docSlug: z.string().min(1),
+        sectionHeading: z.string().nullable(),
+    }))
+        .min(1)
+        .max(5),
+});
+// ---------------------------------------------------------------------------
+// Generator
+// ---------------------------------------------------------------------------
+const CARD_MODEL = mkModelId("anthropic:claude-opus-4-6");
+export const generateTopRecommendations = async (report, ctx) => {
+    // C1: no LLM → missing
+    if (!ctx.llm) {
+        return {
+            status: "missing",
+            cardType: "top-recommendations",
+            reason: "no LLMClient wired",
+        };
+    }
+    // Build allow-list from the runtime report
+    const allowList = buildDocSlugAllowList(report);
+    // Per-call schema: additive docSlug allow-list refine (AI-SPEC §3 Pitfall 1)
+    const PerCallSchema = z.object({
+        summary: z.string().min(1).max(500),
+        suggestions: z
+            .array(z.object({
+            title: z.string().min(1).max(200),
+            body: z
+                .string()
+                .min(40, "suggestion.body must be ≥40 characters")
+                .refine((b) => /`[^`]+`/.test(b), "suggestion.body must contain at least one backtick-delimited artifact"),
+            priority: z.enum(["high", "medium", "low"]),
+            docSlug: z
+                .string()
+                .min(1)
+                .refine((slug) => allowList.has(slug), {
+                message: "suggestion.docSlug is not in the report document manifest allow-list",
+            }),
+            sectionHeading: z.string().nullable(),
+        }))
+            .min(1)
+            .max(5),
+    });
+    const prompt = buildTopRecommendationsPrompt(report, allowList);
+    // Destructure `cost` and `model` from the LLMClient return —
+    // already provided per llm-client.ts:139-144, previously discarded.
+    const { value, usage, cost, model } = await ctx.llm.completeStructured({
+        model: CARD_MODEL,
+        prompt: `${prompt.system}\n\n${prompt.user}`,
+        schema: PerCallSchema,
+        temperature: 0.1,
+        maxTokens: 2000,
+        context: {
+            feature: "diagnosis",
+            runId: ctx.runId,
+            cardId: "top-recommendations",
+        },
+    });
+    return {
+        status: "ready",
+        cardType: "top-recommendations",
+        body: value,
+        meta: {
+            cardVersion: "top-recommendations@0.1.0",
+            tokenUsage: { input: usage.promptTokens, output: usage.completionTokens },
+            generatedAt: new Date().toISOString(),
+            cost,
+            model,
+        },
+    };
+};

package/dist/_vendor/ailf-core/services/diagnosis/cards/weakest-area.d.ts

@@ -0,0 +1,43 @@
+/**
+ * weakest-area card — LLM-driven weakest area identification.
+ *
+ * Model: claude-sonnet-4-6 (routine per AI-SPEC §4 model routing)
+ * Version: weakest-area@0.1.0
+ *
+ * Mitigations:
+ * - failure-mode #3: sampleSize = report.areas[area].judgmentCount (per-call refine W2)
+ * - failure-mode #3: sampleSize < 10 → confidence.level must be "low" (per-call refine W3)
+ * - failure-mode #4: taxonomy drift → buildFailureModeRefinement() Zod predicate
+ *
+ * Per-call schemas live INSIDE the generator (AI-SPEC §3 Pitfall 1 — no
+ * module-scope mutables that change across calls).
+ *
+ * Schema is in the D0045 trust-boundary scan root; `satisfies` clause is
+ * mandatory (cards/ is a SCAN_ROOT in check-trust-boundary-satisfies.ts).
+ *
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-AI-SPEC.md §3
+ */
+import { z } from "zod";
+import type { CardGenerator } from "../../diagnosis-runner.js";
+/**
+ * Module-level schema asserts the static shape + taxonomy constraint (D-05).
+ * Per-call schemas add the sampleSize (W2) and small-sample confidence (W3)
+ * refinements inside the generator, since they need runtime `report` data.
+ */
+export declare const WeakestAreaBodySchema: z.ZodObject<{
+    summary: z.ZodString;
+    area: z.ZodString;
+    dimension: z.ZodString;
+    failureMode: z.ZodString;
+    sampleSize: z.ZodNumber;
+    confidence: z.ZodObject<{
+        level: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
+        signalsPresent: z.ZodNumber;
+        derivation: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const generateWeakestArea: CardGenerator;

package/dist/_vendor/ailf-core/services/diagnosis/cards/weakest-area.js

@@ -0,0 +1,118 @@
+/**
+ * weakest-area card — LLM-driven weakest area identification.
+ *
+ * Model: claude-sonnet-4-6 (routine per AI-SPEC §4 model routing)
+ * Version: weakest-area@0.1.0
+ *
+ * Mitigations:
+ * - failure-mode #3: sampleSize = report.areas[area].judgmentCount (per-call refine W2)
+ * - failure-mode #3: sampleSize < 10 → confidence.level must be "low" (per-call refine W3)
+ * - failure-mode #4: taxonomy drift → buildFailureModeRefinement() Zod predicate
+ *
+ * Per-call schemas live INSIDE the generator (AI-SPEC §3 Pitfall 1 — no
+ * module-scope mutables that change across calls).
+ *
+ * Schema is in the D0045 trust-boundary scan root; `satisfies` clause is
+ * mandatory (cards/ is a SCAN_ROOT in check-trust-boundary-satisfies.ts).
+ *
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-AI-SPEC.md §3
+ */
+import { z } from "zod";
+import { ConfidenceSchema } from "../../../schemas/confidence-schema.js";
+import { modelId as mkModelId } from "../../../ports/llm-client.js";
+import { buildFailureModeRefinement } from "../card-validators.js";
+import { buildWeakestAreaPrompt } from "../prompt-builders.js";
+// ---------------------------------------------------------------------------
+// Module-level schema: static shape + D-05 taxonomy refine
+// ---------------------------------------------------------------------------
+/**
+ * Module-level schema asserts the static shape + taxonomy constraint (D-05).
+ * Per-call schemas add the sampleSize (W2) and small-sample confidence (W3)
+ * refinements inside the generator, since they need runtime `report` data.
+ */
+export const WeakestAreaBodySchema = z
+    .object({
+    summary: z.string().min(1).max(800),
+    area: z.string().min(1),
+    dimension: z.string().min(1),
+    failureMode: z.string().min(1),
+    sampleSize: z.number().int().nonnegative(),
+    confidence: ConfidenceSchema,
+})
+    .refine(buildFailureModeRefinement(), {
+    message: "failureMode is not in the canonical taxonomy for this dimension",
+    path: ["failureMode"],
+});
+// ---------------------------------------------------------------------------
+// Generator
+// ---------------------------------------------------------------------------
+const CARD_MODEL = mkModelId("anthropic:claude-sonnet-4-6");
+export const generateWeakestArea = async (report, ctx) => {
+    // C1: no LLM → missing
+    if (!ctx.llm) {
+        return {
+            status: "missing",
+            cardType: "weakest-area",
+            reason: "no LLMClient wired",
+        };
+    }
+    const scores = report.summary.scores ?? [];
+    if (scores.length === 0) {
+        return {
+            status: "missing",
+            cardType: "weakest-area",
+            reason: "report has no areas",
+        };
+    }
+    // Per-call schema: close over report to get sampleSize + confidence constraints
+    // (AI-SPEC §3 Pitfall 1 — never hoist to module scope)
+    const PerCallSchema = z
+        .object({
+        summary: z.string().min(1).max(800),
+        area: z.string().min(1),
+        dimension: z.string().min(1),
+        failureMode: z.string().min(1),
+        sampleSize: z.number().int().nonnegative(),
+        confidence: ConfidenceSchema,
+    })
+        .refine(buildFailureModeRefinement(), {
+        message: "failureMode is not in the canonical taxonomy for this dimension",
+        path: ["failureMode"],
+    })
+        // W3: small-sample forces confidence.level = "low"
+        .refine((body) => {
+        if (body.sampleSize < 10)
+            return body.confidence.level === "low";
+        return true;
+    }, {
+        message: 'When sampleSize < 10, confidence.level must be "low"',
+        path: ["confidence", "level"],
+    });
+    const prompt = buildWeakestAreaPrompt(report);
+    // Destructure `cost` and `model` from the LLMClient return —
+    // already provided per llm-client.ts:139-144, previously discarded.
+    const { value, usage, cost, model } = await ctx.llm.completeStructured({
+        model: CARD_MODEL,
+        prompt: `${prompt.system}\n\n${prompt.user}`,
+        schema: PerCallSchema,
+        temperature: 0.1,
+        maxTokens: 2000,
+        context: {
+            feature: "diagnosis",
+            runId: ctx.runId,
+            cardId: "weakest-area",
+        },
+    });
+    return {
+        status: "ready",
+        cardType: "weakest-area",
+        body: value,
+        meta: {
+            cardVersion: "weakest-area@0.1.0",
+            tokenUsage: { input: usage.promptTokens, output: usage.completionTokens },
+            generatedAt: new Date().toISOString(),
+            cost,
+            model,
+        },
+    };
+};

package/dist/_vendor/ailf-core/services/diagnosis/prompt-builders.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Deterministic prompt-builder helpers for the 5 LLM diagnosis cards.
+ *
+ * Each function takes typed inputs and returns `{ system, user }` strings
+ * (+ a `deltas` side-channel for regression-vs-baseline). The same inputs
+ * always produce the same output — no randomness, no side effects.
+ *
+ * Per AI-SPEC §4: input tokens are bounded by truncation; the user message
+ * projects only the fields each card needs.
+ *
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-AI-SPEC.md §4
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-AI-SPEC.md §3 lines 603-664
+ */
+import type { JudgmentAttribution } from "../../types/attribution.js";
+import type { Report } from "../../types/index.js";
+/**
+ * Build the allow-list of doc slugs for a report. This is the union of:
+ * - report.summary.documentManifest[].slug
+ * - per-score documents[].slug
+ *
+ * Only slugs (not documentIds) appear in the allow-list because the cards
+ * reference human-readable slugs. DocumentId-only entries are skipped.
+ */
+export declare function buildDocSlugAllowList(report: Report): Set<string>;
+/**
+ * Projects the 3 weakest areas + top failure modes + doc-slug allow-list
+ * into the user message (~2500 input tokens).
+ */
+export declare function buildTopRecommendationsPrompt(report: Report, allowList: Set<string>): {
+    system: string;
+    user: string;
+};
+/**
+ * Projects the single weakest area + full failure-mode breakdown.
+ */
+export declare function buildWeakestAreaPrompt(report: Report): {
+    system: string;
+    user: string;
+};
+/**
+ * Filters to low-confidence entries (or top-N if none low), produces a table
+ * for the LLM (~2000 input tokens).
+ *
+ * Caller short-circuits on empty `judgmentAttributions` BEFORE calling this.
+ */
+export declare function buildLowConfidenceAttributionPrompt(report: Report, judgmentAttributions: JudgmentAttribution[]): {
+    system: string;
+    user: string;
+};
+/**
+ * Aggregates attributions by documentId, picks top-5 by aggregate score,
+ * emits a table for the LLM.
+ *
+ * Caller short-circuits on empty `judgmentAttributions` BEFORE calling this.
+ */
+export declare function buildDocAttributionSpotlightPrompt(report: Report, judgmentAttributions: JudgmentAttribution[]): {
+    system: string;
+    user: string;
+};
+/**
+ * Computes per-area deltas in JS (failure-mode #1 mitigation), then builds
+ * the user message. Returns `deltas` as a side-channel for the per-call
+ * schema `.refine()`.
+ */
+export declare function buildRegressionVsBaselinePrompt(report: Report, baseline: Report): {
+    system: string;
+    user: string;
+    deltas: {
+        area: string;
+        pointsDelta: number;
+    }[];
+};

package/dist/_vendor/ailf-core/services/diagnosis/prompt-builders.js

@@ -0,0 +1,286 @@
+/**
+ * Deterministic prompt-builder helpers for the 5 LLM diagnosis cards.
+ *
+ * Each function takes typed inputs and returns `{ system, user }` strings
+ * (+ a `deltas` side-channel for regression-vs-baseline). The same inputs
+ * always produce the same output — no randomness, no side effects.
+ *
+ * Per AI-SPEC §4: input tokens are bounded by truncation; the user message
+ * projects only the fields each card needs.
+ *
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-AI-SPEC.md §4
+ * @see .planning/phases/05-diagnosis-engine-cli-llm-cards/05-AI-SPEC.md §3 lines 603-664
+ */
+import { TOP_RECOMMENDATIONS_SYSTEM_PROMPT, WEAKEST_AREA_SYSTEM_PROMPT, LOW_CONFIDENCE_ATTRIBUTION_SYSTEM_PROMPT, DOC_ATTRIBUTION_SPOTLIGHT_SYSTEM_PROMPT, REGRESSION_VS_BASELINE_SYSTEM_PROMPT, } from "./prompts/index.js";
+// ---------------------------------------------------------------------------
+// Shared helper: build the docSlug allow-list from a report
+// ---------------------------------------------------------------------------
+/**
+ * Build the allow-list of doc slugs for a report. This is the union of:
+ * - report.summary.documentManifest[].slug
+ * - per-score documents[].slug
+ *
+ * Only slugs (not documentIds) appear in the allow-list because the cards
+ * reference human-readable slugs. DocumentId-only entries are skipped.
+ */
+export function buildDocSlugAllowList(report) {
+    const slugs = new Set();
+    const manifest = report.summary.documentManifest ?? [];
+    for (const doc of manifest) {
+        if ("slug" in doc && typeof doc.slug === "string" && doc.slug.length > 0) {
+            slugs.add(doc.slug);
+        }
+    }
+    for (const score of report.summary.scores ?? []) {
+        for (const doc of score.documents ?? []) {
+            if ("slug" in doc &&
+                typeof doc.slug === "string" &&
+                doc.slug.length > 0) {
+                slugs.add(doc.slug);
+            }
+        }
+    }
+    return slugs;
+}
+// ---------------------------------------------------------------------------
+// top-recommendations prompt builder
+// ---------------------------------------------------------------------------
+/**
+ * Projects the 3 weakest areas + top failure modes + doc-slug allow-list
+ * into the user message (~2500 input tokens).
+ */
+export function buildTopRecommendationsPrompt(report, allowList) {
+    const scores = report.summary.scores ?? [];
+    const sorted = [...scores].sort((a, b) => a.totalScore - b.totalScore);
+    const weakest3 = sorted.slice(0, 3);
+    const failureModes = report.summary.failureModes;
+    const topModes = failureModes?.topTitles
+        ?.slice(0, 5)
+        .map((t) => `${t.category} (${t.count})`) ?? [];
+    const allowListArr = [...allowList].slice(0, 50); // cap at 50 slugs
+    const user = [
+        "## Weakest Areas",
+        weakest3
+            .map((s) => `- ${s.feature}: totalScore=${s.totalScore}, judgmentCount=${s.testCount}`)
+            .join("\n"),
+        "",
+        "## Top Failure Modes",
+        topModes.length > 0 ? topModes.join(", ") : "(none recorded)",
+        "",
+        "## Document Slug Allow-List",
+        "Suggestions MUST use one of these slugs:",
+        allowListArr.map((s) => `- ${s}`).join("\n"),
+        "",
+        "Generate 1-5 actionable recommendations targeting the weakest areas above.",
+    ].join("\n");
+    return { system: TOP_RECOMMENDATIONS_SYSTEM_PROMPT, user };
+}
+// ---------------------------------------------------------------------------
+// weakest-area prompt builder
+// ---------------------------------------------------------------------------
+/**
+ * Projects the single weakest area + full failure-mode breakdown.
+ */
+export function buildWeakestAreaPrompt(report) {
+    const scores = report.summary.scores ?? [];
+    if (scores.length === 0) {
+        return {
+            system: WEAKEST_AREA_SYSTEM_PROMPT,
+            user: "No areas in report.",
+        };
+    }
+    const weakest = [...scores].sort((a, b) => a.totalScore - b.totalScore)[0];
+    const judgmentCount = weakest.testCount ?? 0;
+    const topMode = report.summary.failureModes?.topTitles?.[0]?.category ?? "unclassified";
+    const user = [
+        "## Weakest Area",
+        `Feature: ${weakest.feature}`,
+        `Total Score: ${weakest.totalScore}`,
+        `Ceiling Score: ${weakest.ceilingScore}`,
+        `Floor Score: ${weakest.floorScore}`,
+        `Judgment Count (sampleSize): ${judgmentCount}`,
+        "",
+        "## Top Failure Mode Observed",
+        `Category: ${topMode}`,
+        "",
+        "## Failure Mode by Dimension",
+        report.summary.failureModes?.topTitles
+            ?.slice(0, 5)
+            .map((t) => `- ${t.category}: ${t.count} judgments`)
+            .join("\n") ?? "(no data)",
+        "",
+        "Identify the area, its primary dimension, and most frequent failure mode.",
+        `sampleSize in your response MUST equal exactly ${judgmentCount} (the judgment count above).`,
+        judgmentCount < 10
+            ? `WARNING: sampleSize=${judgmentCount} < 10 — you MUST set confidence.level = "low".`
+            : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return { system: WEAKEST_AREA_SYSTEM_PROMPT, user };
+}
+// ---------------------------------------------------------------------------
+// low-confidence-attribution prompt builder
+// ---------------------------------------------------------------------------
+/**
+ * Filters to low-confidence entries (or top-N if none low), produces a table
+ * for the LLM (~2000 input tokens).
+ *
+ * Caller short-circuits on empty `judgmentAttributions` BEFORE calling this.
+ */
+export function buildLowConfidenceAttributionPrompt(report, judgmentAttributions) {
+    // Filter to low-confidence entries (by any attribution in the set)
+    const lowConf = judgmentAttributions.filter((ja) => ja.attributions.some((a) => a.confidence.level === "low"));
+    // If no low-confidence entries, use all sorted by score ascending (most
+    // uncertain first). Guard against entries with empty `attributions` arrays:
+    // `Math.min(...[])` is Infinity and produces an unstable sort that ranks
+    // empty-attribution entries identically at the top of the prompt. The card
+    // schema requires `judgmentRefs.min(1)`, so emitting empty-attribution rows
+    // here forces a degraded card downstream. Caller should short-circuit to
+    // missing before reaching here, but defend against the seam regressing.
+    const validAttrs = judgmentAttributions.filter((ja) => ja.attributions.length > 0);
+    if (validAttrs.length === 0) {
+        return {
+            system: LOW_CONFIDENCE_ATTRIBUTION_SYSTEM_PROMPT,
+            user: "(no attribution data with non-empty attributions)",
+        };
+    }
+    const source = lowConf.length > 0
+        ? lowConf
+        : [...validAttrs].sort((a, b) => {
+            const aMin = Math.min(...a.attributions.map((x) => x.score));
+            const bMin = Math.min(...b.attributions.map((x) => x.score));
+            return aMin - bMin;
+        });
+    // Cap at 20 to stay within token budget
+    const capped = source.slice(0, 20);
+    const tableRows = capped
+        .map((ja) => {
+        const minConf = ja.attributions.reduce((worst, a) => a.confidence.level === "low"
+            ? "low"
+            : worst === "low"
+                ? "low"
+                : a.confidence.level === "medium"
+                    ? "medium"
+                    : worst, "high");
+        return `| ${ja.judgmentRef} | ${ja.taskId} | ${ja.modelId} | ${ja.dimension} | ${minConf} |`;
+    })
+        .join("\n");
+    const user = [
+        "## Per-Judgment Attribution Confidence",
+        `Total entries: ${judgmentAttributions.length}; Low-confidence: ${lowConf.length}`,
+        "",
+        "| judgmentRef | taskId | modelId | dimension | minConfidence |",
+        "|-------------|--------|---------|-----------|---------------|",
+        tableRows,
+        "",
+        lowConf.length === 0
+            ? "No low-confidence entries found. Return the highest-uncertainty entry and note that confidence is well-calibrated."
+            : `Identify the ${Math.min(lowConf.length, 5)} most uncertain judgments.`,
+    ].join("\n");
+    return { system: LOW_CONFIDENCE_ATTRIBUTION_SYSTEM_PROMPT, user };
+}
+// ---------------------------------------------------------------------------
+// doc-attribution-spotlight prompt builder
+// ---------------------------------------------------------------------------
+/**
+ * Aggregates attributions by documentId, picks top-5 by aggregate score,
+ * emits a table for the LLM.
+ *
+ * Caller short-circuits on empty `judgmentAttributions` BEFORE calling this.
+ */
+export function buildDocAttributionSpotlightPrompt(report, judgmentAttributions) {
+    // Aggregate by documentId (D0052 canonical ref)
+    const byDoc = new Map();
+    for (const ja of judgmentAttributions) {
+        for (const a of ja.attributions) {
+            const entry = byDoc.get(a.documentId) ?? {
+                slug: a.slug,
+                scoreSum: 0,
+                count: 0,
+            };
+            entry.scoreSum += a.score;
+            entry.count += 1;
+            // Keep slug if we have it
+            if (a.slug && !entry.slug)
+                entry.slug = a.slug;
+            byDoc.set(a.documentId, entry);
+        }
+    }
+    // Sort by aggregate score descending, take top 5
+    const sorted = [...byDoc.entries()]
+        .map(([docId, v]) => ({
+        documentId: docId,
+        slug: v.slug,
+        aggregateScore: v.scoreSum / v.count,
+        signalCount: v.count,
+    }))
+        .filter((d) => d.slug) // only emit docs with slugs (allow-list check in Zod)
+        .sort((a, b) => b.aggregateScore - a.aggregateScore)
+        .slice(0, 5);
+    const tableRows = sorted
+        .map((d) => `| ${d.documentId} | ${d.slug ?? "(no slug)"} | ${d.aggregateScore.toFixed(3)} | ${d.signalCount} |`)
+        .join("\n");
+    const user = [
+        "## Top Documents by Attribution Score",
+        `Total unique documents: ${byDoc.size}`,
+        "",
+        "| documentId | slug | aggregateScore | signalCount |",
+        "|------------|------|----------------|-------------|",
+        tableRows,
+        "",
+        "For each document in the table, determine its role (supports/contradicts/missing/irrelevant).",
+        "docSlug in your output MUST exactly match the slug column — do not invent slugs.",
+    ].join("\n");
+    return { system: DOC_ATTRIBUTION_SPOTLIGHT_SYSTEM_PROMPT, user };
+}
+// ---------------------------------------------------------------------------
+// regression-vs-baseline prompt builder
+// ---------------------------------------------------------------------------
+/**
+ * Computes per-area deltas in JS (failure-mode #1 mitigation), then builds
+ * the user message. Returns `deltas` as a side-channel for the per-call
+ * schema `.refine()`.
+ */
+export function buildRegressionVsBaselinePrompt(report, baseline) {
+    // Build area → score maps
+    const currentByArea = new Map((report.summary.scores ?? []).map((s) => [s.feature, s.totalScore]));
+    const baselineByArea = new Map((baseline.summary.scores ?? []).map((s) => [s.feature, s.totalScore]));
+    // Only compute deltas for areas present in BOTH reports
+    const deltas = [];
+    for (const [area, current] of currentByArea) {
+        const base = baselineByArea.get(area);
+        if (base !== undefined) {
+            deltas.push({
+                area,
+                pointsDelta: parseFloat((current - base).toFixed(2)),
+            });
+        }
+    }
+    // Sort by absolute delta descending (most changed first), cap at 10
+    const topDeltas = deltas
+        .sort((a, b) => Math.abs(b.pointsDelta) - Math.abs(a.pointsDelta))
+        .slice(0, 10);
+    const deltaRows = topDeltas
+        .map((d) => `| ${d.area} | ${d.pointsDelta > 0 ? "+" : ""}${d.pointsDelta} | ${d.pointsDelta > 0 ? "improved" : d.pointsDelta < 0 ? "regressed" : "unchanged"} |`)
+        .join("\n");
+    const user = [
+        "## Pre-Computed Score Deltas (current minus baseline)",
+        "These values are FACTS — do not modify them.",
+        "",
+        "| area | pointsDelta | expectedDirection |",
+        "|------|-------------|-------------------|",
+        deltaRows,
+        "",
+        "For each row, echo the exact area + pointsDelta, assign the matching direction label, and add prose drivers.",
+        "Do NOT round or change any numeric value.",
+        "",
+        `Current run: ${report.provenance.runId}`,
+        `Baseline run: ${baseline.provenance.runId}`,
+    ].join("\n");
+    return {
+        system: REGRESSION_VS_BASELINE_SYSTEM_PROMPT,
+        user,
+        deltas: topDeltas,
+    };
+}