@mergesignal/shared 0.2.2 → 0.2.4

package/dist/productMessaging.js

@@ -0,0 +1,109 @@
+import { CARD_EXPOSURE_CATEGORY_LABELS } from "./formatCardExposureDisplay.js";
+import { MERGE_POSTURE_LABEL } from "./riskVocabulary.js";
+/**
+ * Canonical marketing / category copy. Operational scan strings stay in scanSurfaceCopy.
+ */
+export const productMessaging = {
+    formalDefinition: "MergeSignal analyzes dependency upgrades, identifies affected application flows, and provides reviewer guidance before merge.",
+    hero: {
+        kicker: "Merge-decision intelligence for dependency upgrades",
+        h1: "See what a dependency upgrade can break.",
+        lead: "Dependency upgrade analysis that shows where runtime behavior may affect critical application flows.",
+    },
+    seo: {
+        title: "MergeSignal - know what an upgrade may break before merge",
+        description: "Know what a dependency upgrade may affect in your app before merge. Affected flows, reviewer checks, and merge guidance for this PR.",
+    },
+    finalCta: {
+        headline: "Try it on your next upgrade PR",
+        lead: "Run a local scan or add GitHub Actions to your workflow.",
+        button: "Get started for free",
+    },
+    homepageSections: {
+        pain: {
+            title: "Why dependency upgrades are hard to review",
+            subhead: "Upgrading is easy. Knowing what it affects is not.",
+            rows: [
+                {
+                    title: "Changelogs don't show real impact",
+                    body: "Release notes describe package changes, not how they affect your code paths and critical application flows.",
+                },
+                {
+                    title: "Too much noise, not enough clarity",
+                    body: "Security alerts rarely show what actually matters for this specific upgrade PR.",
+                },
+                {
+                    title: "Runtime impact is hard to reason about",
+                    body: "Understanding how a dependency change affects critical application flows requires deeper application context.",
+                },
+            ],
+        },
+        focus: {
+            title: "What MergeSignal focuses on",
+            subhead: "Clearer upgrade decisions with fewer merge surprises",
+            rows: [
+                {
+                    title: "What this upgrade affects",
+                    body: "Potential failure modes based on how your code uses the updated dependencies.",
+                },
+                {
+                    title: "Where it shows up",
+                    body: "The application flows, routes, and entrypoints affected by this upgrade.",
+                },
+                {
+                    title: "What to verify before merge",
+                    body: "Concrete reviewer checks for this specific upgrade.",
+                },
+            ],
+        },
+        value: {
+            title: "What changes when you use MergeSignal",
+            subhead: "More focused reviews and targeted validation.",
+            rows: [
+                {
+                    title: "Reviews move faster",
+                    body: "Start with affected flows instead of reconstructing impact from changelogs.",
+                },
+                {
+                    title: "Testing stays targeted",
+                    body: "Focus validation on the flows this upgrade affects.",
+                },
+                {
+                    title: "Fewer merge surprises",
+                    body: "Catch upgrade impact while the PR is still small.",
+                },
+                {
+                    title: "High-signal only",
+                    body: "MergeSignal only interrupts you when an upgrade deserves attention.",
+                },
+            ],
+        },
+    },
+    /** Repository dashboard PR cards — reviewer-oriented semantics (not engine/scoring docs). */
+    dashboardPrCard: {
+        intro: "The repository dashboard is a runtime-aware review surface for open upgrade pull requests: triage by merge recommendation, then read operational context on each card.",
+        posture: `Posture indicates the merge recommendation (${MERGE_POSTURE_LABEL.safe}, ${MERGE_POSTURE_LABEL.needs_review}, ${MERGE_POSTURE_LABEL.risky}).`,
+        exposure: "Exposure indicates how broadly the upgrade touches runtime-relevant application areas.",
+        exposureCategoriesLead: "On each scanned card, exposure reads as one of:",
+        exposureCategories: CARD_EXPOSURE_CATEGORY_LABELS,
+        cardBody: "Below the verdict, scanned cards surface up to three compact operational observations (transitive volume, blast radius, duplicate versions, and related topology signals) when the engine finds mappable structure.",
+    },
+};
+/** Illustrative scan-card example for homepage proof band and getting-started. */
+export const primaryPrExample = {
+    package: "express",
+    message: "This upgrade affects middleware ordering used in auth routes.",
+    where: [
+        "apps/api/src/middleware/auth.ts - auth guard depends on middleware order",
+        "apps/api/src/routes/account.ts - protected handlers assume validation ran first",
+    ],
+};
+/** All homepage section row bodies for word-count validation. */
+export function homepageSectionRowBodies() {
+    const sections = productMessaging.homepageSections;
+    return [
+        ...sections.pain.rows,
+        ...sections.value.rows,
+        ...sections.focus.rows,
+    ].map((row) => row.body);
+}

package/dist/productMessaging.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=productMessaging.test.d.ts.map

package/dist/productMessaging.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"productMessaging.test.d.ts","sourceRoot":"","sources":["../src/productMessaging.test.ts"],"names":[],"mappings":""}

package/dist/productMessaging.test.js

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { homepageSectionRowBodies, primaryPrExample, productMessaging, } from "./productMessaging.js";
+const LOCKED_H1 = "See what a dependency upgrade can break.";
+const FORBIDDEN_MARKETING_TERMS = [
+    "runtime-aware",
+    "AI-powered",
+    "framework-aware",
+    "observability",
+    "exhaustive indexing",
+    "repo analytics",
+    "risk platform",
+    "risk intelligence platform",
+    "security analysis platform",
+    "scanner platform",
+];
+describe("productMessaging", () => {
+    it("locks hero H1 exactly including trailing period", () => {
+        expect(productMessaging.hero.h1).toBe(LOCKED_H1);
+        expect(productMessaging.hero.h1.endsWith(".")).toBe(true);
+    });
+    it("keeps lead separate from H1", () => {
+        expect(productMessaging.hero.lead).not.toBe(productMessaging.hero.h1);
+    });
+    it("uses express middleware example for marketing card", () => {
+        expect(primaryPrExample.package).toBe("express");
+        expect(primaryPrExample.message).toContain("middleware ordering");
+        expect(primaryPrExample.where).toHaveLength(2);
+    });
+    it("uses engineering-native example domains", () => {
+        const text = [primaryPrExample.message, ...primaryPrExample.where].join(" ");
+        expect(text.toLowerCase()).toMatch(/auth|middleware|routes/);
+    });
+    it("keeps section row bodies under 20 words", () => {
+        for (const body of homepageSectionRowBodies()) {
+            const wordCount = body.trim().split(/\s+/).length;
+            expect(wordCount).toBeLessThanOrEqual(20);
+        }
+    });
+    it("avoids em dashes in marketing copy", () => {
+        const strings = collectMarketingStrings();
+        for (const s of strings) {
+            expect(s).not.toMatch(/[\u2013\u2014]/);
+        }
+    });
+    it("avoids forbidden marketing terms in hero and seo", () => {
+        const heroSeo = [
+            productMessaging.hero.kicker,
+            productMessaging.hero.h1,
+            productMessaging.hero.lead,
+            productMessaging.seo.title,
+            productMessaging.seo.description,
+            productMessaging.formalDefinition,
+        ].join(" ");
+        for (const term of FORBIDDEN_MARKETING_TERMS) {
+            expect(heroSeo.toLowerCase()).not.toContain(term.toLowerCase());
+        }
+    });
+    it("does not expose comparison hooks in hero exports", () => {
+        expect(productMessaging.hero.kicker).not.toContain("Dependabot");
+        expect(productMessaging.hero.h1).not.toContain("Dependabot");
+        expect(productMessaging.hero.lead).not.toContain("Dependabot");
+    });
+    it("describes dashboard posture and exposure without scoring jargon", () => {
+        const d = productMessaging.dashboardPrCard;
+        const text = [
+            d.intro,
+            d.posture,
+            d.exposure,
+            d.exposureCategoriesLead,
+            ...d.exposureCategories,
+            d.cardBody,
+        ].join(" ");
+        expect(text).toContain("merge recommendation");
+        expect(text).toContain("runtime-relevant");
+        expect(text).not.toMatch(/risk index|total score|0-100|formula|weight/i);
+        expect(d.exposureCategories).toHaveLength(5);
+        expect(d.exposureCategories).toContain("Elevated exposure");
+    });
+});
+function collectMarketingStrings() {
+    const out = [
+        productMessaging.formalDefinition,
+        productMessaging.hero.kicker,
+        productMessaging.hero.h1,
+        productMessaging.hero.lead,
+        productMessaging.seo.title,
+        productMessaging.seo.description,
+        primaryPrExample.message,
+        ...primaryPrExample.where,
+    ];
+    for (const body of homepageSectionRowBodies()) {
+        out.push(body);
+    }
+    const d = productMessaging.dashboardPrCard;
+    out.push(d.intro, d.posture, d.exposure, d.exposureCategoriesLead, d.cardBody, ...d.exposureCategories);
+    return out;
+}

package/dist/riskVocabulary.d.ts

@@ -2,6 +2,12 @@ import type { PRDecisionRecommendation } from "./types.js";
 export type MergePosture = PRDecisionRecommendation;
 /** Canonical display strings for merge posture values. */
 export declare const MERGE_POSTURE_LABEL: Record<MergePosture, string>;
+/**
+ * Dashboard card badge labels. Defaults to full canonical names for triage clarity.
+ * Wire values remain `safe | needs_review | risky`.
+ */
+export declare const CARD_POSTURE_DISPLAY_LABEL: Record<MergePosture, string>;
+export declare function cardPostureDisplayLabel(posture: MergePosture): string;
 /**
  * Sorting weights: higher number = listed first (riskiest first).
  * Use as: arr.sort((a, b) => MERGE_POSTURE_SORT_ORDER[b] - MERGE_POSTURE_SORT_ORDER[a])
@@ -16,8 +22,8 @@ export declare function mergePostureLabel(decision: string | null | undefined, f
  * e.g. "Risky, risk score 72" or "Safe"
  */
 export declare function ariaLabelForPosture(decision: string | null | undefined, score: number | null | undefined): string;
-/** Accessible label for unified PR card risk block. */
-export declare function ariaLabelForCardSummary(headline: string, riskIndex: number | null | undefined, summaryLine: string | null | undefined): string;
+/** Accessible label for unified PR card findings block. */
+export declare function ariaLabelForCardSummary(postureLabel: string, riskIndex: number | null | undefined, observations: string[] | null | undefined, supportingLine?: string | null): string;
 export type SignalSeverity = "low" | "medium" | "high";
 /**
  * Format a signal severity for prose use — always returns a qualified string

package/dist/riskVocabulary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"riskVocabulary.d.ts","sourceRoot":"","sources":["../src/riskVocabulary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAkB3D,MAAM,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAEpD,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAI5D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAIjE,CAAC;AAEF,0EAA0E;AAC1E,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAClC,YAAY,GAAG,IAAI,CASrB;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,QAAQ,SAAM,GACb,MAAM,CAGR;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,CAIR;AAED,uDAAuD;AACvD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,MAAM,CAKR;AAMD,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAQvD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG3E"}
+{"version":3,"file":"riskVocabulary.d.ts","sourceRoot":"","sources":["../src/riskVocabulary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAkB3D,MAAM,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAEpD,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAI5D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAEnE,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAErE;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAIjE,CAAC;AAEF,0EAA0E;AAC1E,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAClC,YAAY,GAAG,IAAI,CASrB;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,QAAQ,SAAM,GACb,MAAM,CAGR;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,CAKR;AAED,2DAA2D;AAC3D,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EACzC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,GAC7B,MAAM,CASR;AAMD,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAQvD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG3E"}

package/dist/riskVocabulary.js

@@ -1,9 +1,20 @@
+import { exposureAriaFragment } from "./formatCardExposureDisplay.js";
 /** Canonical display strings for merge posture values. */
 export const MERGE_POSTURE_LABEL = {
     safe: "Safe",
     needs_review: "Needs review",
     risky: "Risky",
 };
+/**
+ * Dashboard card badge labels. Defaults to full canonical names for triage clarity.
+ * Wire values remain `safe | needs_review | risky`.
+ */
+export const CARD_POSTURE_DISPLAY_LABEL = {
+    ...MERGE_POSTURE_LABEL,
+};
+export function cardPostureDisplayLabel(posture) {
+    return CARD_POSTURE_DISPLAY_LABEL[posture];
+}
 /**
  * Sorting weights: higher number = listed first (riskiest first).
  * Use as: arr.sort((a, b) => MERGE_POSTURE_SORT_ORDER[b] - MERGE_POSTURE_SORT_ORDER[a])
@@ -33,17 +44,23 @@ export function mergePostureLabel(decision, fallback = "—") {
  */
 export function ariaLabelForPosture(decision, score) {
     const label = mergePostureLabel(decision);
-    if (score != null)
-        return `${label}, risk score ${Math.round(score)}`;
+    const exposure = exposureAriaFragment(score);
+    if (exposure)
+        return `${label}, ${exposure}`;
     return label;
 }
-/** Accessible label for unified PR card risk block. */
-export function ariaLabelForCardSummary(headline, riskIndex, summaryLine) {
-    const parts = [headline];
-    if (riskIndex != null)
-        parts.push(`risk index ${Math.round(riskIndex)}`);
-    if (summaryLine?.trim())
-        parts.push(summaryLine.trim());
+/** Accessible label for unified PR card findings block. */
+export function ariaLabelForCardSummary(postureLabel, riskIndex, observations, supportingLine) {
+    const parts = [postureLabel];
+    const exposure = exposureAriaFragment(riskIndex);
+    if (exposure)
+        parts.push(exposure);
+    for (const obs of observations ?? []) {
+        if (obs?.trim())
+            parts.push(obs.trim());
+    }
+    if (supportingLine?.trim())
+        parts.push(supportingLine.trim());
     return parts.join(". ");
 }
 const SIGNAL_SEVERITY_LABEL = {

package/dist/scanCardSummary.d.ts

@@ -1,3 +1,4 @@
+import type { CatalogPhrase } from "./cardObservationCatalog.js";
 import { type MergePosture } from "./riskVocabulary.js";
 import type { Finding, ScanResult } from "./types.js";
 export type ScanPipelineStatus = "queued" | "running" | "done" | "failed";
@@ -14,9 +15,15 @@ export type ScanCardSummary = {
     riskIndex: number | null;
     riskIndexBand: RiskIndexBand | null;
     headline: string;
+    /** @deprecated Use operationalObservations */
     summaryLine: string | null;
     findingCounts: FindingCountSummary | null;
+    /** @deprecated Use operationalObservations */
     topAffectedAreas: string[];
+    /** Catalog-mapped topology observations (0–3). */
+    operationalObservations: CatalogPhrase[];
+    /** Optional quiet subline when exactly one observation is shown. */
+    supportingLine: string | null;
 };
 export declare const SCAN_CARD_SCANNING_SUMMARY = "Waiting for results\u2026";
 export type PipelineCompletionEvidence = {
@@ -42,6 +49,8 @@ export declare function aggregateFindingCounts(findings: Finding[] | null | unde
 /**
  * Server-side card summary for PR dashboard list views.
  * Pipeline lifecycle copy is included when `pipelineStatus !== "done"`.
+ *
+ * Quiet safe cards with no mappable signals show posture + exposure only.
  */
 export declare function deriveScanCardSummary(result: ScanResult | null | undefined, pipelineStatus: ScanPipelineStatus): ScanCardSummary;
 /** Subline appended when scan results are stale (head SHA mismatch). */

package/dist/scanCardSummary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanCardSummary.d.ts","sourceRoot":"","sources":["../src/scanCardSummary.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scanCardSummary.d.ts","sourceRoot":"","sources":["../src/scanCardSummary.ts"],"names":[],"mappings":"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"}

package/dist/scanCardSummary.js

@@ -1,8 +1,7 @@
-import { deriveScanSummaryText } from "./deriveScanSummaryText.js";
+import { deriveCardOperationalObservations } from "./deriveCardOperationalObservations.js";
 import { mergePostureFromDecision, MERGE_POSTURE_LABEL, } from "./riskVocabulary.js";
 import { scanSurfaceCopy } from "./scanSurfaceCopy.js";
 import { selectTopAffectedAreas } from "./selectTopAffectedAreas.js";
-const SAFE_SUMMARY = "No merge blockers detected";
 const STALE_SUBLINE = "Based on earlier commit";
 export const SCAN_CARD_SCANNING_SUMMARY = "Waiting for results…";
 function normalizePipelineStatus(status) {
@@ -94,18 +93,11 @@ export function aggregateFindingCounts(findings) {
     }
     return counts;
 }
-function hasActionableFindings(counts) {
-    return counts.critical + counts.high + counts.medium + counts.low > 0;
-}
-function deriveSafeSummaryLine(posture, counts, fallback) {
-    if (posture === "safe" && !hasActionableFindings(counts)) {
-        return SAFE_SUMMARY;
-    }
-    return fallback;
-}
 /**
  * Server-side card summary for PR dashboard list views.
  * Pipeline lifecycle copy is included when `pipelineStatus !== "done"`.
+ *
+ * Quiet safe cards with no mappable signals show posture + exposure only.
  */
 export function deriveScanCardSummary(result, pipelineStatus) {
     if (pipelineStatus === "queued" || pipelineStatus === "running") {
@@ -117,6 +109,8 @@ export function deriveScanCardSummary(result, pipelineStatus) {
             summaryLine: SCAN_CARD_SCANNING_SUMMARY,
             findingCounts: null,
             topAffectedAreas: [],
+            operationalObservations: [],
+            supportingLine: null,
         };
     }
     if (pipelineStatus === "failed") {
@@ -128,6 +122,8 @@ export function deriveScanCardSummary(result, pipelineStatus) {
             summaryLine: null,
             findingCounts: null,
             topAffectedAreas: [],
+            operationalObservations: [],
+            supportingLine: null,
         };
     }
     if (!result) {
@@ -139,27 +135,33 @@ export function deriveScanCardSummary(result, pipelineStatus) {
             summaryLine: null,
             findingCounts: null,
             topAffectedAreas: [],
+            operationalObservations: [],
+            supportingLine: null,
         };
     }
     const posture = mergePostureFromDecision(result.decision?.recommendation) ?? null;
     const riskIndex = typeof result.totalScore === "number" ? result.totalScore : null;
     const riskIndexBand = deriveRiskIndexBand(riskIndex);
     const findingCounts = aggregateFindingCounts(result.findings);
-    const summaryFromText = deriveScanSummaryText(result);
     const headline = posture
         ? MERGE_POSTURE_LABEL[posture]
         : scanSurfaceCopy.checkRun.mergePostureUnavailable;
-    const summaryLine = posture
-        ? deriveSafeSummaryLine(posture, findingCounts, summaryFromText)
-        : summaryFromText;
+    const topAffectedAreas = selectTopAffectedAreas(result, { max: 2 });
+    const { operationalObservations, supportingLine } = deriveCardOperationalObservations(result, {
+        mergePosture: posture,
+        hasFullResult: true,
+        max: 3,
+    });
     return {
         mergePosture: posture,
         riskIndex,
         riskIndexBand,
         headline,
-        summaryLine,
+        summaryLine: null,
         findingCounts,
-        topAffectedAreas: selectTopAffectedAreas(result, { max: 2 }),
+        topAffectedAreas,
+        operationalObservations,
+        supportingLine,
     };
 }
 /** Subline appended when scan results are stale (head SHA mismatch). */
@@ -187,18 +189,6 @@ export function deriveScanCardSummaryFromDenormalized(decision, totalScore, summ
             : undefined,
     };
     const summary = deriveScanCardSummary(minimalResult, "done");
-    const sanitized = isPipelinePlaceholderCopy(summaryText)
-        ? null
-        : (summaryText?.trim() ?? null);
-    if (sanitized && !summary.summaryLine) {
-        return { ...summary, summaryLine: sanitized };
-    }
-    if (sanitized &&
-        posture &&
-        summary.summaryLine === SAFE_SUMMARY &&
-        sanitized !== SAFE_SUMMARY) {
-        return { ...summary, summaryLine: sanitized };
-    }
     return summary;
 }
 /**

package/dist/scanCardSummary.test.js

@@ -1,4 +1,5 @@
 import { describe, it, expect } from "vitest";
+import { isCatalogPhrase } from "./cardObservationCatalog.js";
 import { aggregateFindingCounts, deriveRiskIndexBand, deriveScanCardSummary, deriveScanCardSummaryFromDenormalized, isPipelineCardSummary, isPipelinePlaceholderCopy, resolvePipelineStatus, resolvePrScanCardSummary, staleScanSubline, } from "./scanCardSummary.js";
 const baseResult = {
     totalScore: 10,
@@ -71,15 +72,26 @@ describe("deriveScanCardSummary", () => {
                 confidence: "high",
                 reasoning: ["Auth boundary change"],
             },
+            explain: {
+                reasons: [
+                    {
+                        id: "upgrade.1",
+                        layer: "upgradeImpact",
+                        title: "Large upgrade blast radius",
+                        scoreImpact: 20,
+                    },
+                ],
+            },
         };
         const summary = deriveScanCardSummary(r, "done");
         expect(summary.mergePosture).toBe("risky");
         expect(summary.headline).toBe("Risky");
         expect(summary.riskIndex).toBe(72);
         expect(summary.riskIndexBand).toBe("high");
-        expect(summary.summaryLine).toBe("Auth boundary change");
+        expect(summary.summaryLine).toBeNull();
+        expect(summary.operationalObservations).toContain("Large upgrade blast radius");
     });
-    it("uses safe copy when posture is safe and no findings", () => {
+    it("keeps quiet safe cards posture-only without observations", () => {
         const r = {
             ...baseResult,
             totalScore: 12,
@@ -90,9 +102,10 @@ describe("deriveScanCardSummary", () => {
             },
         };
         const summary = deriveScanCardSummary(r, "done");
-        expect(summary.summaryLine).toBe("No merge blockers detected");
+        expect(summary.summaryLine).toBeNull();
+        expect(summary.operationalObservations).toEqual([]);
     });
-    it("caps top affected areas at 2", () => {
+    it("surfaces catalog observations from explain signals", () => {
         const r = {
             ...baseResult,
             decision: {
@@ -102,14 +115,28 @@ describe("deriveScanCardSummary", () => {
             },
             explain: {
                 reasons: [
-                    { id: "1", layer: "security", title: "A", scoreImpact: -10 },
-                    { id: "2", layer: "security", title: "B", scoreImpact: -9 },
+                    {
+                        id: "1",
+                        layer: "ecosystem",
+                        title: "graph.transitive volume",
+                        scoreImpact: 18,
+                    },
+                    {
+                        id: "2",
+                        layer: "ecosystem",
+                        title: "graph.duplicates",
+                        scoreImpact: 12,
+                    },
                     { id: "3", layer: "security", title: "C", scoreImpact: -8 },
                 ],
             },
         };
         const summary = deriveScanCardSummary(r, "done");
         expect(summary.topAffectedAreas).toHaveLength(2);
+        expect(summary.operationalObservations.length).toBeGreaterThan(0);
+        for (const phrase of summary.operationalObservations) {
+            expect(isCatalogPhrase(phrase)).toBe(true);
+        }
     });
     it("exports stale subline constant", () => {
         expect(staleScanSubline()).toBe("Based on earlier commit");
@@ -149,6 +176,8 @@ describe("isPipelineCardSummary", () => {
             summaryLine: "Waiting for results…",
             findingCounts: null,
             topAffectedAreas: [],
+            operationalObservations: [],
+            supportingLine: null,
         })).toBe(true);
     });
     it("detects hybrid completed posture with pipeline summary line", () => {
@@ -160,6 +189,8 @@ describe("isPipelineCardSummary", () => {
             summaryLine: "Waiting for results…",
             findingCounts: null,
             topAffectedAreas: [],
+            operationalObservations: [],
+            supportingLine: null,
         })).toBe(true);
     });
 });
@@ -170,18 +201,24 @@ describe("isPipelinePlaceholderCopy", () => {
     });
 });
 describe("deriveScanCardSummaryFromDenormalized", () => {
-    it("builds risky summary from denormalized columns", () => {
+    it("builds risky summary from denormalized columns without generic narration", () => {
         const summary = deriveScanCardSummaryFromDenormalized("risky", 72, "Auth boundary change", "done");
         expect(summary.mergePosture).toBe("risky");
         expect(summary.headline).toBe("Risky");
         expect(summary.riskIndex).toBe(72);
-        expect(summary.summaryLine).toBe("Auth boundary change");
+        expect(summary.summaryLine).toBeNull();
+        expect(summary.operationalObservations).toEqual([]);
     });
     it("does not inject pipeline placeholder summaryText", () => {
         const summary = deriveScanCardSummaryFromDenormalized("risky", 72, "Waiting for results…", "done");
         expect(summary.mergePosture).toBe("risky");
         expect(summary.summaryLine).not.toBe("Waiting for results…");
     });
+    it("does not inject raw generic summaryText on quiet safe cards", () => {
+        const summary = deriveScanCardSummaryFromDenormalized("safe", 12, "No high-confidence merge risks from this PR dependency change", "done");
+        expect(summary.mergePosture).toBe("safe");
+        expect(summary.summaryLine).toBeNull();
+    });
 });
 describe("resolvePrScanCardSummary", () => {
     it("returns risk summary when wire status is running but decision exists", () => {