@mergesignal/shared 0.2.7 → 0.2.8

package/dist/prCheckRunPresentation.js

@@ -2,9 +2,12 @@
  * GitHub Check Run markdown — policy → sections → dumb renderer.
  * Thin projection of ScanResult for PR decision support (not a presentation framework).
  */
-import { deriveScanSummaryText } from "./deriveScanSummaryText.js";
+import { collectWhyBullets } from "./collectNarrativeWhyBullets.js";
+import { deriveScanNarrative } from "./deriveScanNarrative.js";
 import { formatInsight } from "./formatInsight.js";
-import { humanizeEngineSurfaceText, layerDriverSummary, sortPRInsightsForDisplay, sortRecommendationsForDisplay, truncateWithEllipsis, } from "./actionsStepSummary.js";
+import { normalizeGeneratedText } from "./normalizeGeneratedText.js";
+import { selectReviewerGuidance } from "./narrativePresentation.js";
+import { layerDriverSummary, sortPRInsightsForDisplay, sortRecommendationsForDisplay, truncateWithEllipsis, } from "./actionsStepSummary.js";
 import { mergePostureLabel } from "./riskVocabulary.js";
 import { scanSurfaceCopy } from "./scanSurfaceCopy.js";
 // --- Caps (change only with tests) ---
@@ -40,43 +43,17 @@ export function formatScanDashboardUrl(webAppOrigin, scanId) {
 export function buildPrCheckRunTitle(opts = {}) {
     const base = scanSurfaceCopy.checkRun.titleBase;
     if (opts.baselineOnly) {
-        return `${base} – ${scanSurfaceCopy.checkRun.titleBaselineSuffix}`;
+        return `${base} - ${scanSurfaceCopy.checkRun.titleBaselineSuffix}`;
     }
     return base;
 }
-function collectWhyBullets(result, max) {
-    const out = [];
-    const reasoning = result.decision?.reasoning;
-    if (Array.isArray(reasoning)) {
-        for (const r of reasoning) {
-            const s = humanizeEngineSurfaceText(String(r).trim());
-            if (s && !out.includes(s))
-                out.push(s);
-            if (out.length >= max)
-                return out.slice(0, max);
-        }
-    }
-    const reasons = result.explain?.reasons;
-    if (Array.isArray(reasons) && out.length < max) {
-        for (const r of reasons) {
-            const title = String(r?.title ?? r?.id ?? "").trim();
-            const readable = humanizeEngineSurfaceText(title);
-            if (readable && !out.includes(readable))
-                out.push(readable);
-            if (out.length >= max)
-                break;
-        }
-    }
-    if (out.length === 0) {
-        const one = deriveScanSummaryText(result);
-        if (one)
-            out.push(one);
-    }
-    return out.slice(0, max);
-}
 /** Strong drivers for optional repo-context line (full mode only). */
-export function hasStrongRepoGraphDrivers(result) {
-    const phrases = collectWhyBullets(result, CHECK_RUN_MAX_REPO_DRIVER_PHRASES);
+export function hasStrongRepoGraphDrivers(result, facts) {
+    if (facts?.availability.mode === "pr_intelligence" ||
+        facts?.availability.tiersPresent.tier1) {
+        return false;
+    }
+    const phrases = collectWhyBullets(facts ?? deriveScanNarrative(result), result, CHECK_RUN_MAX_REPO_DRIVER_PHRASES);
     return phrases.some((p) => p.trim().length >= 12);
 }
 function hasActionableBullets(result) {
@@ -92,7 +69,7 @@ function insightToBullet(insight) {
     const msg = truncateWithEllipsis(f.message, CHECK_RUN_ACTION_BULLET_MAX_CHARS);
     const action = f.action.trim();
     if (action && action.length < 120) {
-        return `${msg} — ${truncateWithEllipsis(action, 100)}`;
+        return normalizeGeneratedText(`${msg} - ${truncateWithEllipsis(action, 100)}`);
     }
     return msg;
 }
@@ -100,7 +77,7 @@ function recommendationToBullet(rec) {
     const title = String(rec.title ?? "").trim();
     const rat = String(rec.rationale ?? "").trim();
     const pkgs = Array.isArray(rec.packages) && rec.packages.length > 0
-        ? ` (${rec.packages.slice(0, 3).join(", ")}${rec.packages.length > 3 ? ", …" : ""})`
+        ? ` (${rec.packages.slice(0, 3).join(", ")}${rec.packages.length > 3 ? ", ..." : ""})`
         : "";
     if (rat && (!title || rat.length > title.length)) {
         return truncateWithEllipsis(rat, CHECK_RUN_ACTION_BULLET_MAX_CHARS) + pkgs;
@@ -113,6 +90,31 @@ function findingToBullet(f) {
     const pkg = f.packageName ? ` (\`${f.packageName}\`)` : "";
     return (truncateWithEllipsis(title || f.description, CHECK_RUN_ACTION_BULLET_MAX_CHARS) + pkg);
 }
+function guidanceToActionBullet(g) {
+    const msg = truncateWithEllipsis(g.message.trim(), CHECK_RUN_ACTION_BULLET_MAX_CHARS);
+    const action = g.remediation?.trim();
+    if (action && action.length < 120) {
+        return normalizeGeneratedText(`${msg} - ${truncateWithEllipsis(action, 100)}`);
+    }
+    return normalizeGeneratedText(msg);
+}
+function buildActionBulletsFromFacts(facts, result, max) {
+    const prIntel = facts.availability.mode === "pr_intelligence" ||
+        facts.availability.tiersPresent.tier1;
+    if (!prIntel) {
+        return buildActionBullets(result, max);
+    }
+    const out = [];
+    for (const g of selectReviewerGuidance(facts, { scope: "changed", max })) {
+        out.push(guidanceToActionBullet(g));
+        if (out.length >= max)
+            return out.slice(0, max);
+    }
+    if (out.length >= max)
+        return out.slice(0, max);
+    const legacy = buildActionBullets(result, max - out.length);
+    return [...out, ...legacy].slice(0, max);
+}
 function buildActionBullets(result, max) {
     const out = [];
     const sortedI = sortPRInsightsForDisplay(Array.isArray(result.insights) ? result.insights : []);
@@ -156,12 +158,13 @@ function layerScoreRows(result) {
     }
     return rows;
 }
-export function deriveCheckRunPolicy(result, ctx) {
+export function deriveCheckRunPolicy(result, ctx, facts) {
+    const resolvedFacts = facts ?? deriveScanNarrative(result);
     const baseline = ctx.baseline;
-    const actionBullets = buildActionBullets(result, CHECK_RUN_MAX_ACTION_BULLETS);
+    const actionBullets = buildActionBulletsFromFacts(resolvedFacts, result, CHECK_RUN_MAX_ACTION_BULLETS);
     const layerRows = layerScoreRows(result);
     const showRepoGraphContext = !baseline &&
-        hasStrongRepoGraphDrivers(result) &&
+        hasStrongRepoGraphDrivers(result, resolvedFacts) &&
         typeof result.totalScore === "number" &&
         Number.isFinite(result.totalScore);
     const showLayerScores = !baseline && layerRows.length > 0;
@@ -189,14 +192,15 @@ function buildLeadSection(result, policy) {
         : null;
     return { kind: "lead", posture, riskIndexLine };
 }
-export function buildPrCheckRunSections(policy, result, ctx) {
+export function buildPrCheckRunSections(policy, result, ctx, facts) {
+    const resolvedFacts = facts ?? deriveScanNarrative(result);
     const sections = {};
     sections.lead = buildLeadSection(result, policy);
-    const why = collectWhyBullets(result, policy.maxWhyBullets);
+    const why = collectWhyBullets(resolvedFacts, result, policy.maxWhyBullets);
     if (why.length > 0) {
         sections.why = { kind: "why", bullets: why };
     }
-    const actions = buildActionBullets(result, policy.maxActionBullets);
+    const actions = buildActionBulletsFromFacts(resolvedFacts, result, policy.maxActionBullets);
     if (actions.length > 0) {
         sections.actions = { kind: "actions", bullets: actions };
     }
@@ -212,7 +216,7 @@ export function buildPrCheckRunSections(policy, result, ctx) {
         sections.repoContext = {
             kind: "repoContext",
             score,
-            driverPhrases: collectWhyBullets(result, policy.maxRepoDriverPhrases),
+            driverPhrases: collectWhyBullets(resolvedFacts, result, policy.maxRepoDriverPhrases),
         };
     }
     if (policy.showLayerScores) {
@@ -270,8 +274,8 @@ export function renderCheckRunMarkdown(sections) {
                 break;
             }
             case "repoContext": {
-                const drivers = section.driverPhrases.join(" · ");
-                parts.push(`${scanSurfaceCopy.checkRun.repoContextLabel} ${section.score}/100 — ${drivers}`);
+                const drivers = section.driverPhrases.join(" | ");
+                parts.push(normalizeGeneratedText(`${scanSurfaceCopy.checkRun.repoContextLabel} ${section.score}/100 - ${drivers}`));
                 parts.push("");
                 break;
             }
@@ -280,7 +284,7 @@ export function renderCheckRunMarkdown(sections) {
                 parts.push(`<summary>${scanSurfaceCopy.checkRun.layerScoresDetailsSummary}</summary>`);
                 parts.push("");
                 for (const row of section.rows) {
-                    parts.push(`- **${row.label}** ${row.score}/100 — ${row.driver}`);
+                    parts.push(normalizeGeneratedText(`- **${row.label}** ${row.score}/100 - ${row.driver}`));
                 }
                 parts.push("");
                 parts.push("</details>");
@@ -297,15 +301,16 @@ export function renderCheckRunMarkdown(sections) {
             }
         }
     }
-    let md = parts.join("\n").trimEnd();
+    let md = normalizeGeneratedText(parts.join("\n").trimEnd());
     if (md.length > CHECK_RUN_SOFT_MAX_CHARS) {
-        md = md.slice(0, CHECK_RUN_SOFT_MAX_CHARS - 1) + "…";
+        md = md.slice(0, CHECK_RUN_SOFT_MAX_CHARS - 1) + "...";
     }
     return md;
 }
 export function buildPrCheckRunSummaryMarkdown(ctx) {
-    const policy = deriveCheckRunPolicy(ctx.result, { baseline: ctx.baseline });
-    const sections = buildPrCheckRunSections(policy, ctx.result, ctx);
+    const facts = deriveScanNarrative(ctx.result);
+    const policy = deriveCheckRunPolicy(ctx.result, { baseline: ctx.baseline }, facts);
+    const sections = buildPrCheckRunSections(policy, ctx.result, ctx, facts);
     return renderCheckRunMarkdown(sections);
 }
 /** Whether baseline scan has no actionable PR bullets (for tests / callers). */

package/dist/prCheckRunPresentation.test.js

@@ -38,7 +38,7 @@ describe("buildPrCheckRunTitle", () => {
         expect(buildPrCheckRunTitle()).not.toContain("—");
     });
     it("appends baseline suffix when requested", () => {
-        expect(buildPrCheckRunTitle({ baselineOnly: true })).toBe("PR dependency change – baseline scan only");
+        expect(buildPrCheckRunTitle({ baselineOnly: true })).toBe("PR dependency change - baseline scan only");
     });
 });
 describe("formatScanDashboardUrl", () => {
@@ -271,7 +271,7 @@ describe("buildPrCheckRunSummaryMarkdown", () => {
             baseline: false,
         });
         if (md.includes("Layer scores")) {
-            expect(md).toMatch(/Maintainability.*\/100 —/);
+            expect(md).toMatch(/Maintainability.*\/100 -/);
             expect(md).not.toMatch(/\| Security \| 0 \|/);
         }
     });

package/dist/presentGitHubPrComment.d.ts

@@ -0,0 +1,9 @@
+import type { ScanNarrativeFacts } from "./scanNarrativeFacts.js";
+import type { PRDecision, PRInsight, ScanResult } from "./types.js";
+/**
+ * PR comment markdown from narrative facts (compressed dashboard story).
+ */
+export declare function presentGitHubPrComment(facts: ScanNarrativeFacts, result: ScanResult): string;
+/** Backward-compatible entry: derives facts then presents. */
+export declare function renderInsightsAsMarkdown(insights: PRInsight[], decision: PRDecision): string;
+//# sourceMappingURL=presentGitHubPrComment.d.ts.map

package/dist/presentGitHubPrComment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentGitHubPrComment.d.ts","sourceRoot":"","sources":["../src/presentGitHubPrComment.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAoBpE;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,UAAU,GACjB,MAAM,CA6CR;AAED,8DAA8D;AAC9D,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,EAAE,EACrB,QAAQ,EAAE,UAAU,GACnB,MAAM,CAgBR"}

package/dist/presentGitHubPrComment.js

@@ -0,0 +1,80 @@
+import { deriveScanNarrative } from "./deriveScanNarrative.js";
+import { composeVerificationPrompt, formatChangedPackagesShort, formatUsageSummaryLine, selectReviewerGuidance, } from "./narrativePresentation.js";
+import { normalizeGeneratedText } from "./normalizeGeneratedText.js";
+import { MERGE_POSTURE_LABEL, mergePostureFromDecision, } from "./riskVocabulary.js";
+import { scanSurfaceCopy } from "./scanSurfaceCopy.js";
+function renderGuidanceBlock(message, where, action) {
+    return [
+        normalizeGeneratedText(message),
+        "",
+        "**Where it shows up**",
+        "",
+        normalizeGeneratedText(where),
+        "",
+        "**What to do**",
+        "",
+        normalizeGeneratedText(action),
+    ].join("\n");
+}
+/**
+ * PR comment markdown from narrative facts (compressed dashboard story).
+ */
+export function presentGitHubPrComment(facts, result) {
+    const posture = facts.mergePosture ??
+        mergePostureFromDecision(result.decision?.recommendation);
+    const title = posture
+        ? `**${MERGE_POSTURE_LABEL[posture]}**`
+        : `**${scanSurfaceCopy.checkRun.mergePostureUnavailable}**`;
+    const introLines = [];
+    const changed = formatChangedPackagesShort(facts, 3);
+    if (changed)
+        introLines.push(`Changed: ${changed}`);
+    const usage = formatUsageSummaryLine(facts, 1);
+    if (usage)
+        introLines.push(usage);
+    const verify = composeVerificationPrompt(facts);
+    if (verify)
+        introLines.push(`Verify: ${verify}`);
+    const guidance = selectReviewerGuidance(facts, { scope: "changed", max: 3 });
+    if (guidance.length === 0) {
+        const fallback = selectReviewerGuidance(facts, { max: 3 });
+        guidance.push(...fallback.slice(0, 3 - guidance.length));
+    }
+    const blocks = guidance.map((g) => {
+        const where = g.context?.trim() ||
+            facts.packageUsage
+                .flatMap((u) => u.paths.slice(0, 1))
+                .filter(Boolean)[0] ||
+            "See scan detail for affected paths.";
+        const action = g.remediation?.trim() ||
+            composeVerificationPrompt(facts) ||
+            "Review before merge.";
+        return renderGuidanceBlock(g.message, where, action);
+    });
+    const parts = [title];
+    if (introLines.length > 0) {
+        parts.push("", introLines.join("\n"));
+    }
+    if (blocks.length > 0) {
+        parts.push("", ...blocks);
+    }
+    return parts.join("\n\n---\n\n").trimEnd();
+}
+/** Backward-compatible entry: derives facts then presents. */
+export function renderInsightsAsMarkdown(insights, decision) {
+    const result = {
+        totalScore: 0,
+        layerScores: {
+            security: 0,
+            maintainability: 0,
+            ecosystem: 0,
+            upgradeImpact: 0,
+        },
+        findings: [],
+        generatedAt: new Date().toISOString(),
+        insights,
+        decision,
+    };
+    const facts = deriveScanNarrative(result);
+    return presentGitHubPrComment(facts, result);
+}

package/dist/presentScanCardSummary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presentScanCardSummary.d.ts","sourceRoot":"","sources":["../src/presentScanCardSummary.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,6BAA6B,GAAG;IAC1C,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;CACnC,CAAC;AA2HF;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,6BAAkC,GAC1C,eAAe,CAkGjB;AAED,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,CAAC;AAElD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,kBAAkB,GACxB,mBAAmB,GAAG,IAAI,CAE5B"}
+{"version":3,"file":"presentScanCardSummary.d.ts","sourceRoot":"","sources":["../src/presentScanCardSummary.ts"],"names":[],"mappings":"AAKA,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,gCAAgC,CAAC;AAkBxC,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,6BAA6B,GAAG;IAC1C,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;CACnC,CAAC;AA2HF;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,6BAAkC,GAC1C,eAAe,CA8HjB;AAED,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,CAAC;AAElD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,kBAAkB,GACxB,mBAAmB,GAAG,IAAI,CAE5B"}

package/dist/presentScanCardSummary.js

@@ -1,35 +1,11 @@
-import { phraseForFamily, } from "./cardObservationCatalog.js";
-import { aggregateFindingCounts, deriveRiskIndexBand, } from "./scanCardSummary.js";
+import { isCatalogPhrase, phraseForFamily, } from "./cardObservationCatalog.js";
+import { aggregateFindingCounts, deriveRiskIndexBand, SCAN_CARD_SCANNING_SUMMARY, } from "./scanCardSummary.js";
 import { deriveCardExposureDisplay, } from "./formatCardExposureDisplay.js";
 import { formatCardAreaLabels } from "./formatCardAreaLabels.js";
+import { composeContextLineFromFacts, composeVerificationPrompt, formatBlastRadiusDetailLine, formatChangedPackagesShort, formatFrameworksSummary, formatUsageSummaryLine, labelBlastRadiusLevel, labelReachabilityKind, labelRuntimeSurface, } from "./narrativePresentation.js";
+import { normalizeGeneratedText, normalizeGeneratedTextNullable, } from "./normalizeGeneratedText.js";
 import { MERGE_POSTURE_LABEL } from "./riskVocabulary.js";
 import { scanSurfaceCopy } from "./scanSurfaceCopy.js";
-function formatChangedPackagesDisplay(facts) {
-    const { primary, others } = facts.changedPackages;
-    if (!primary)
-        return null;
-    if (others.length === 0)
-        return primary;
-    return `${primary} +${others.length}`;
-}
-function labelRuntimeSurface(facts) {
-    const rs = facts.runtimeSurface;
-    if (!rs)
-        return null;
-    return scanSurfaceCopy.narrativeCard.runtimeSurface[rs.kind];
-}
-function labelReachability(facts) {
-    const r = facts.reachability;
-    if (!r)
-        return null;
-    return scanSurfaceCopy.narrativeCard.reachability[r.kind];
-}
-function labelBlastRadius(facts) {
-    const br = facts.blastRadius;
-    if (!br)
-        return null;
-    return scanSurfaceCopy.narrativeCard.blastRadius[br.level];
-}
 function formatAffectedAreaLabels(facts) {
     const ordered = [];
     for (const area of facts.affectedAreas) {
@@ -62,7 +38,7 @@ function selectSecondaryLines(facts, exclude) {
     }
     return lines;
 }
-function repositoryContextPhrases(facts) {
+function repositoryContextPhrases(facts, max) {
     const phrases = [];
     const seen = new Set();
     for (const ctx of facts.repositoryContext) {
@@ -71,32 +47,13 @@ function repositoryContextPhrases(facts) {
             continue;
         seen.add(phrase);
         phrases.push(phrase);
-        if (phrases.length >= 3)
+        if (phrases.length >= max)
             break;
     }
     return phrases;
 }
-function composeContextLine(facts) {
-    const parts = [];
-    const runtime = labelRuntimeSurface(facts);
-    const reach = labelReachability(facts);
-    const blast = labelBlastRadius(facts);
-    if (runtime)
-        parts.push(runtime);
-    if (reach)
-        parts.push(reach);
-    if (blast)
-        parts.push(blast);
-    const areas = formatAffectedAreaLabels(facts);
-    if (areas.length > 0) {
-        parts.push(areas.join(scanSurfaceCopy.narrativeCard.areasSeparator));
-    }
-    if (parts.length === 0)
-        return null;
-    return parts.join(scanSurfaceCopy.narrativeCard.contextSeparator);
-}
-function buildLegacyObservations(facts, primaryInsight) {
-    const repoPhrases = repositoryContextPhrases(facts);
+function buildLegacyObservations(facts, primaryInsight, repoPhraseCap) {
+    const repoPhrases = repositoryContextPhrases(facts, repoPhraseCap);
     const secondary = selectSecondaryLines(facts, primaryInsight);
     if (primaryInsight) {
         return {
@@ -110,10 +67,34 @@ function buildLegacyObservations(facts, primaryInsight) {
         return { operationalObservations: [], supportingLine: null };
     }
     return {
-        operationalObservations: repoPhrases.slice(0, 3),
+        operationalObservations: repoPhrases.slice(0, repoPhraseCap),
         supportingLine: repoPhrases.length === 1 ? (secondary[0] ?? null) : null,
     };
 }
+function normalizeCardSummary(summary) {
+    return {
+        ...summary,
+        headline: normalizeGeneratedText(summary.headline),
+        summaryLine: normalizeGeneratedTextNullable(summary.summaryLine),
+        supportingLine: normalizeGeneratedTextNullable(summary.supportingLine),
+        changedPackagesDisplay: normalizeGeneratedTextNullable(summary.changedPackagesDisplay),
+        runtimeSurfaceLabel: normalizeGeneratedTextNullable(summary.runtimeSurfaceLabel),
+        reachabilityLabel: normalizeGeneratedTextNullable(summary.reachabilityLabel),
+        blastRadiusLabel: normalizeGeneratedTextNullable(summary.blastRadiusLabel),
+        primaryInsight: normalizeGeneratedTextNullable(summary.primaryInsight),
+        structuralOnlyDisclaimer: normalizeGeneratedTextNullable(summary.structuralOnlyDisclaimer),
+        usageSummary: normalizeGeneratedTextNullable(summary.usageSummary),
+        verificationLine: normalizeGeneratedTextNullable(summary.verificationLine),
+        blastRadiusDetail: normalizeGeneratedTextNullable(summary.blastRadiusDetail),
+        frameworksSummary: normalizeGeneratedTextNullable(summary.frameworksSummary),
+        affectedAreas: summary.affectedAreas.map((a) => normalizeGeneratedText(a)),
+        topAffectedAreas: summary.topAffectedAreas.map((a) => normalizeGeneratedText(a)),
+        operationalObservations: summary.operationalObservations.map((p) => {
+            const normalized = normalizeGeneratedText(p);
+            return isCatalogPhrase(normalized) ? normalized : p;
+        }),
+    };
+}
 /**
  * Dashboard card presentation DTO from consumer-agnostic facts.
  */
@@ -129,23 +110,27 @@ export function presentScanCardSummary(facts, options = {}) {
         affectedAreas: [],
         primaryInsight: null,
         structuralOnlyDisclaimer: null,
+        usageSummary: null,
+        verificationLine: null,
+        blastRadiusDetail: null,
+        frameworksSummary: null,
     };
     if (pipelineStatus === "queued" || pipelineStatus === "running") {
-        return {
+        return normalizeCardSummary({
             mergePosture: null,
             riskIndex: null,
             riskIndexBand: null,
             headline: scanSurfaceCopy.pipeline.scanRunning,
-            summaryLine: "Waiting for results…",
+            summaryLine: SCAN_CARD_SCANNING_SUMMARY,
             findingCounts: null,
             topAffectedAreas: [],
             operationalObservations: [],
             supportingLine: null,
             ...emptyPresentationFields,
-        };
+        });
     }
     if (pipelineStatus === "failed") {
-        return {
+        return normalizeCardSummary({
             mergePosture: null,
             riskIndex: null,
             riskIndexBand: null,
@@ -156,7 +141,7 @@ export function presentScanCardSummary(facts, options = {}) {
             operationalObservations: [],
             supportingLine: null,
             ...emptyPresentationFields,
-        };
+        });
     }
     const posture = facts.mergePosture;
     const riskIndex = facts.riskIndex;
@@ -167,12 +152,17 @@ export function presentScanCardSummary(facts, options = {}) {
     const findingCounts = options.findings
         ? aggregateFindingCounts(options.findings)
         : null;
-    const changedPackagesDisplay = formatChangedPackagesDisplay(facts);
+    const prIntelligence = facts.availability.mode === "pr_intelligence" ||
+        facts.availability.tiersPresent.tier1;
+    const changedPackagesDisplay = formatChangedPackagesShort(facts, 2);
     const runtimeSurfaceLabel = labelRuntimeSurface(facts);
-    const reachabilityLabel = labelReachability(facts);
-    const blastRadiusLabel = labelBlastRadius(facts);
+    const reachabilityLabel = labelReachabilityKind(facts);
+    const blastRadiusLabel = labelBlastRadiusLevel(facts);
     const affectedAreas = formatAffectedAreaLabels(facts);
-    const contextLine = composeContextLine(facts);
+    const contextLine = composeContextLineFromFacts(facts, {
+        includePathSample: prIntelligence,
+        maxAreas: 2,
+    });
     const structuralOnlyDisclaimer = facts.availability.mode === "graph_fallback" &&
         !facts.availability.tiersPresent.tier1
         ? scanSurfaceCopy.narrativeCard.structuralOnlyDisclaimer
@@ -180,8 +170,19 @@ export function presentScanCardSummary(facts, options = {}) {
     const insightMessage = selectPrimaryInsight(facts);
     const primaryInsight = insightMessage ??
         (facts.availability.mode !== "graph_fallback" ? contextLine : null);
-    const { operationalObservations, supportingLine } = buildLegacyObservations(facts, primaryInsight);
-    return {
+    const usageSummary = prIntelligence ? formatUsageSummaryLine(facts, 1) : null;
+    const verificationLine = prIntelligence
+        ? composeVerificationPrompt(facts)
+        : null;
+    const blastRadiusDetail = prIntelligence
+        ? formatBlastRadiusDetailLine(facts, 1)
+        : null;
+    const frameworksSummary = prIntelligence
+        ? formatFrameworksSummary(facts, 2)
+        : null;
+    const repoPhraseCap = prIntelligence ? 0 : 3;
+    const { operationalObservations, supportingLine } = buildLegacyObservations(facts, primaryInsight, repoPhraseCap);
+    return normalizeCardSummary({
         mergePosture: posture,
         riskIndex,
         riskIndexBand,
@@ -200,7 +201,11 @@ export function presentScanCardSummary(facts, options = {}) {
         affectedAreas,
         primaryInsight,
         structuralOnlyDisclaimer,
-    };
+        usageSummary,
+        verificationLine,
+        blastRadiusDetail,
+        frameworksSummary,
+    });
 }
 export function exposureFromFacts(facts) {
     return deriveCardExposureDisplay(facts.riskIndex) ?? null;

package/dist/riskVocabulary.js

@@ -34,7 +34,7 @@ export function mergePostureFromDecision(decision) {
     return null;
 }
 /** Returns the display label for a decision, or a fallback string. */
-export function mergePostureLabel(decision, fallback = "—") {
+export function mergePostureLabel(decision, fallback = "-") {
     const posture = mergePostureFromDecision(decision);
     return posture ? MERGE_POSTURE_LABEL[posture] : fallback;
 }

package/dist/scanCardSummary.d.ts

@@ -34,8 +34,16 @@ export type ScanCardSummary = {
     affectedAreas: string[];
     primaryInsight: string | null;
     structuralOnlyDisclaimer: string | null;
+    /** One-line usage hint from packageUsage paths or areas. */
+    usageSummary: string | null;
+    /** Single verification prompt from changed-scope guidance or usage. */
+    verificationLine: string | null;
+    /** Optional blast factor subline when factors exist. */
+    blastRadiusDetail: string | null;
+    /** Short framework list (max 2 on card). */
+    frameworksSummary: string | null;
 };
-export declare const SCAN_CARD_SCANNING_SUMMARY = "Waiting for results\u2026";
+export declare const SCAN_CARD_SCANNING_SUMMARY = "Waiting for results...";
 export type PipelineCompletionEvidence = {
     scannedAt?: string | null;
     decision?: string | null;

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

@@ -3,7 +3,7 @@ import { presentScanCardSummary } from "./presentScanCardSummary.js";
 import { mergePostureFromDecision, } from "./riskVocabulary.js";
 import { scanSurfaceCopy } from "./scanSurfaceCopy.js";
 const STALE_SUBLINE = "Based on earlier commit";
-export const SCAN_CARD_SCANNING_SUMMARY = "Waiting for results…";
+export const SCAN_CARD_SCANNING_SUMMARY = "Waiting for results...";
 function normalizePipelineStatus(status) {
     const st = String(status ?? "")
         .trim()

package/dist/scanCardSummary.test.js

@@ -11,6 +11,10 @@ const pipelinePresentationDefaults = {
     affectedAreas: [],
     primaryInsight: null,
     structuralOnlyDisclaimer: null,
+    usageSummary: null,
+    verificationLine: null,
+    blastRadiusDetail: null,
+    frameworksSummary: null,
 };
 const baseResult = {
     totalScore: 10,
@@ -64,7 +68,7 @@ describe("deriveScanCardSummary", () => {
     it("returns scanning copy for queued/running", () => {
         const queued = deriveScanCardSummary(null, "queued");
         expect(queued.headline).toBe("Scan in progress");
-        expect(queued.summaryLine).toBe("Waiting for results…");
+        expect(queued.summaryLine).toBe("Waiting for results...");
         expect(queued.mergePosture).toBeNull();
         const running = deriveScanCardSummary(null, "running");
         expect(running.headline).toBe("Scan in progress");
@@ -184,7 +188,7 @@ describe("isPipelineCardSummary", () => {
             riskIndex: null,
             riskIndexBand: null,
             headline: "Scan in progress",
-            summaryLine: "Waiting for results…",
+            summaryLine: "Waiting for results...",
             findingCounts: null,
             topAffectedAreas: [],
             operationalObservations: [],
@@ -198,7 +202,7 @@ describe("isPipelineCardSummary", () => {
             riskIndex: 72,
             riskIndexBand: "high",
             headline: "Risky",
-            summaryLine: "Waiting for results…",
+            summaryLine: "Waiting for results...",
             findingCounts: null,
             topAffectedAreas: [],
             operationalObservations: [],
@@ -209,7 +213,7 @@ describe("isPipelineCardSummary", () => {
 });
 describe("isPipelinePlaceholderCopy", () => {
     it("identifies waiting copy", () => {
-        expect(isPipelinePlaceholderCopy("Waiting for results…")).toBe(true);
+        expect(isPipelinePlaceholderCopy("Waiting for results...")).toBe(true);
         expect(isPipelinePlaceholderCopy("Auth change")).toBe(false);
     });
 });
@@ -223,9 +227,9 @@ describe("deriveScanCardSummaryFromDenormalized", () => {
         expect(summary.operationalObservations).toEqual([]);
     });
     it("does not inject pipeline placeholder summaryText", () => {
-        const summary = deriveScanCardSummaryFromDenormalized("risky", 72, "Waiting for results…", "done");
+        const summary = deriveScanCardSummaryFromDenormalized("risky", 72, "Waiting for results...", "done");
         expect(summary.mergePosture).toBe("risky");
-        expect(summary.summaryLine).not.toBe("Waiting for results…");
+        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");
@@ -239,11 +243,11 @@ describe("resolvePrScanCardSummary", () => {
             pipelineStatus: "running",
             decision: "risky",
             totalScore: 80,
-            summaryText: "Waiting for results…",
+            summaryText: "Waiting for results...",
             result: null,
         });
         expect(summary.mergePosture).toBe("risky");
         expect(summary.headline).toBe("Risky");
-        expect(summary.summaryLine).not.toBe("Waiting for results…");
+        expect(summary.summaryLine).not.toBe("Waiting for results...");
     });
 });