@mergesignal/shared 0.11.0 → 0.12.0

package/dist/assessmentProjection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assessmentProjection.d.ts","sourceRoot":"","sources":["../src/assessmentProjection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EACV,UAAU,EACV,4BAA4B,EAC5B,eAAe,EACf,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AAOhC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAmDlE,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,qBAAqB,GAC/B,mBAAmB,CAIrB;AAED,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAQ5E;AAED,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAS7E;AAED,wBAAgB,uCAAuC,CACrD,YAAY,EAAE,4BAA4B,EAC1C,MAAM,EAAE,UAAU,GACjB;IAAE,OAAO,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAWnD;AAED,8FAA8F;AAC9F,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAErE;AAED,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,eAAe,GAC1B,MAAM,GAAG,SAAS,CAWpB;AAED,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,kBAAkB,GACzB,MAAM,CAiDR;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAIlE;AAED,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,UAAU,GACjB,MAAM,EAAE,CAaV;AAED,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,4BAA4B,EAC1C,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,CAOV;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,gBAAgB,GAAG,IAAI,GAAG,MAAM,EAAE,CAI3E"}
+{"version":3,"file":"assessmentProjection.d.ts","sourceRoot":"","sources":["../src/assessmentProjection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EACV,UAAU,EACV,4BAA4B,EAC5B,eAAe,EACf,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AAOhC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAmDlE,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,qBAAqB,GAC/B,mBAAmB,CAIrB;AAED,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAQ5E;AAED,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAS7E;AAED,wBAAgB,uCAAuC,CACrD,YAAY,EAAE,4BAA4B,EAC1C,MAAM,EAAE,UAAU,GACjB;IAAE,OAAO,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAWnD;AAED,8FAA8F;AAC9F,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAErE;AAED,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,eAAe,GAC1B,MAAM,GAAG,SAAS,CAWpB;AAED,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,kBAAkB,GACzB,MAAM,CAiDR;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAMlE;AAED,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,UAAU,GACjB,MAAM,EAAE,CAaV;AAED,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,4BAA4B,EAC1C,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,CAWV;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,gBAAgB,GAAG,IAAI,GAAG,MAAM,EAAE,CAI3E"}

package/dist/assessmentProjection.js

@@ -126,10 +126,12 @@ export function formatAssessmentHeadline(assessment, status) {
     return applyPostureVocabularyGuardHeadline(copy.defaultUpgradeHeadline.replace("{package}", primaryPkg), status, primaryPkg);
 }
 export function projectReasoningLines(result) {
-    const fromDecision = result.decision?.reasoning?.filter(Boolean) ?? [];
-    if (fromDecision.length > 0)
-        return fromDecision.slice(0, 3);
-    return [];
+    // ABI 3: assessment.reasoning is the authoritative source for repository-specific prose
+    const fromAssessment = result.assessment?.reasoning?.filter(Boolean) ?? [];
+    if (fromAssessment.length > 0)
+        return fromAssessment;
+    // Fallback for pre-ABI-3 scan results still in the database
+    return result.decision?.reasoning?.filter(Boolean) ?? [];
 }
 export function projectInsightLines(assessment, result) {
     const reasoning = projectReasoningLines(result);
@@ -149,6 +151,11 @@ export function projectInsightLines(assessment, result) {
 export function projectVerificationActions(assessment, presentation, result, max) {
     if (presentation.verificationIntensity === "none")
         return [];
+    // ABI 3: use actionable prose guidance when present
+    const guidance = assessment.verificationScope?.guidance;
+    if (guidance && guidance.length > 0)
+        return guidance.slice(0, max);
+    // Fallback: focus tokens from legacy scope or repoIntelligence
     const { focus } = collectVerificationFocusForPresentation(presentation, result);
     return focus.slice(0, max);
 }

package/dist/fixtures/assessmentScopeFixtures.d.ts

@@ -10,8 +10,11 @@ export declare function emptyArtifactGrounded(): ArtifactGroundedVerificationSco
 export declare function artifactGroundedScopeFor(packages: string[], focus?: string[], artifactPaths?: string[]): ArtifactGroundedVerificationScope;
 export declare function emptyVerificationScope(): VerificationScope;
 export declare function verificationScopeFor(packages: string[], focus?: string[], artifactGrounded?: ArtifactGroundedVerificationScope): VerificationScope;
-/** Attach focal/scope fields required by assessmentSchema ABI 2. */
-export declare function withAssessmentScope(assessment: Omit<Assessment, "reviewFocalPoint" | "reachScope" | "verificationScope">, scope: {
+/** Attach focal/scope fields required by assessmentSchema ABI 3. */
+export declare function withAssessmentScope(assessment: Omit<Assessment, "reviewFocalPoint" | "reachScope" | "verificationScope" | "reasoning" | "confidenceRationale"> & {
+    reasoning?: string[];
+    confidenceRationale?: string;
+}, scope: {
     reviewFocalPoint: ReviewFocalPoint;
     reachScope?: ReachScope;
     verificationScope?: VerificationScope;

package/dist/fixtures/assessmentScopeFixtures.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assessmentScopeFixtures.d.ts","sourceRoot":"","sources":["../../src/fixtures/assessmentScopeFixtures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iCAAiC,EACjC,UAAU,EACV,sBAAsB,EACtB,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAEhC,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,CAAC,EAAE;IACL,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC,GACA,gBAAgB,CAoBlB;AAED,wBAAgB,eAAe,IAAI,UAAU,CAE5C;AAED,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAAE,EAClB,SAAS,GAAE,UAAU,CAAC,WAAW,CAAc,GAC9C,UAAU,CAEZ;AAED,wBAAgB,qBAAqB,IAAI,iCAAiC,CAEzE;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAAE,EAClB,KAAK,GAAE,MAAM,EAAO,EACpB,aAAa,GAAE,MAAM,EAAO,GAC3B,iCAAiC,CAEnC;AAED,wBAAgB,sBAAsB,IAAI,iBAAiB,CAM1D;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAAE,EAClB,KAAK,GAAE,MAAM,EAAO,EACpB,gBAAgB,GAAE,iCAA2D,GAC5E,iBAAiB,CAEnB;AAED,oEAAoE;AACpE,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,IAAI,CACd,UAAU,EACV,kBAAkB,GAAG,YAAY,GAAG,mBAAmB,CACxD,EACD,KAAK,EAAE;IACL,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC,GACA,UAAU,CAOZ"}
+{"version":3,"file":"assessmentScopeFixtures.d.ts","sourceRoot":"","sources":["../../src/fixtures/assessmentScopeFixtures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iCAAiC,EACjC,UAAU,EACV,sBAAsB,EACtB,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAEhC,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,CAAC,EAAE;IACL,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC,GACA,gBAAgB,CAoBlB;AAED,wBAAgB,eAAe,IAAI,UAAU,CAE5C;AAED,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAAE,EAClB,SAAS,GAAE,UAAU,CAAC,WAAW,CAAc,GAC9C,UAAU,CAEZ;AAED,wBAAgB,qBAAqB,IAAI,iCAAiC,CAEzE;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAAE,EAClB,KAAK,GAAE,MAAM,EAAO,EACpB,aAAa,GAAE,MAAM,EAAO,GAC3B,iCAAiC,CAEnC;AAED,wBAAgB,sBAAsB,IAAI,iBAAiB,CAM1D;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAAE,EAClB,KAAK,GAAE,MAAM,EAAO,EACpB,gBAAgB,GAAE,iCAA2D,GAC5E,iBAAiB,CAEnB;AAED,oEAAoE;AACpE,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,IAAI,CACd,UAAU,EACR,kBAAkB,GAClB,YAAY,GACZ,mBAAmB,GACnB,WAAW,GACX,qBAAqB,CACxB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAE,EAC1D,KAAK,EAAE;IACL,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC,GACA,UAAU,CASZ"}

package/dist/fixtures/assessmentScopeFixtures.js

@@ -41,9 +41,11 @@ export function emptyVerificationScope() {
 export function verificationScopeFor(packages, focus = [], artifactGrounded = emptyArtifactGrounded()) {
     return { packages, focus, artifactGrounded };
 }
-/** Attach focal/scope fields required by assessmentSchema ABI 2. */
+/** Attach focal/scope fields required by assessmentSchema ABI 3. */
 export function withAssessmentScope(assessment, scope) {
     return {
+        reasoning: [],
+        confidenceRationale: "",
         ...assessment,
         reviewFocalPoint: scope.reviewFocalPoint,
         reachScope: scope.reachScope ?? emptyReachScope(),

package/dist/presentation/abi3Expression.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Wave 2.D — ABI 3 expression validation.
+ *
+ * Validates that:
+ * 1. projectReasoningLines reads from assessment.reasoning (ABI 3) when present
+ * 2. projectVerificationActions returns assessment.verificationScope.guidance when present
+ * 3. PR comment includes reviewFocalPoint.electionSummary when present
+ * 4. Check run "Why" section uses assessment.reasoning lines directly
+ * 5. No prohibited vocabulary appears in rendered surfaces
+ * 6. assessment.reasoning takes priority over decision.reasoning
+ */
+export {};
+//# sourceMappingURL=abi3Expression.test.d.ts.map

package/dist/presentation/abi3Expression.test.d.ts.map

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

package/dist/presentation/abi3Expression.test.js

@@ -0,0 +1,346 @@
+/**
+ * Wave 2.D — ABI 3 expression validation.
+ *
+ * Validates that:
+ * 1. projectReasoningLines reads from assessment.reasoning (ABI 3) when present
+ * 2. projectVerificationActions returns assessment.verificationScope.guidance when present
+ * 3. PR comment includes reviewFocalPoint.electionSummary when present
+ * 4. Check run "Why" section uses assessment.reasoning lines directly
+ * 5. No prohibited vocabulary appears in rendered surfaces
+ * 6. assessment.reasoning takes priority over decision.reasoning
+ */
+import { describe, expect, it } from "vitest";
+import { minimalReviewFocalPoint, reachScopeFor, verificationScopeFor, withAssessmentScope, } from "../fixtures/assessmentScopeFixtures.js";
+import { projectReasoningLines, projectVerificationActions, } from "../assessmentProjection.js";
+import { toPublicPresentation } from "../assessmentPresentationUtils.js";
+import { buildScanPresentationBundle } from "./orchestration/buildScanPresentationBundle.js";
+import { presentGitHubPrComment } from "./presenters/presentGitHubPrComment.js";
+import { presentGitHubCheckRun } from "./presenters/presentGitHubCheckRun.js";
+import { buildGitHubCheckRunOutput } from "./buildGitHubCheckRunOutput.js";
+import { presentGitHubPrCommentMarkdownFromResult } from "../presentGitHubPrComment.js";
+// ---------------------------------------------------------------------------
+// ABI 3 — Canonical express/confirmed_runtime_usage fixture
+// ---------------------------------------------------------------------------
+const expressReasoning = [
+    "express is used in HTTP request handling in this repository via middleware chains.",
+    "Import paths to application entry points were directly observed.",
+    "Verification is required: review HTTP route definitions and middleware implementation.",
+];
+const expressGuidance = [
+    "Review HTTP route definitions and middleware implementation in src/app.ts and src/server.ts.",
+    "Review handler implementations that use express routing.",
+];
+const expressElectionSummary = "express was selected as the primary review anchor because it has the highest repository reach among changed packages and confirmed runtime usage in HTTP request handling.";
+const assessmentExpressAbi3 = withAssessmentScope({
+    posture: "needs_review",
+    confidence: "high",
+    primaryConcern: "confirmed_runtime_usage",
+    concerns: [
+        {
+            kind: "confirmed_runtime_usage",
+            rank: 1,
+            packages: ["express"],
+            evidenceRefs: ["fixture:express"],
+            context: "express participates in HTTP request handling across 12 files.",
+        },
+    ],
+    factors: ["confirmed_runtime_usage", "http_framework_infrastructure"],
+    changeClasses: ["runtime_upgrade"],
+    presentation: {
+        narrativeIntensity: "elevated",
+        reachVisibility: "prominent",
+        verificationIntensity: "required",
+        insightEmissionFloor: "full",
+        reportMode: "high_signal_pr",
+    },
+    reasoning: expressReasoning,
+    confidenceRationale: "Confidence is high: propagation from express to application entry points was directly observed.",
+}, {
+    reviewFocalPoint: {
+        ...minimalReviewFocalPoint(["express"]),
+        electionSummary: expressElectionSummary,
+    },
+    reachScope: reachScopeFor(["express"], "high"),
+    verificationScope: verificationScopeFor(["express"], ["routes", "middleware"], undefined),
+});
+const assessmentExpressAbi3WithGuidance = {
+    ...assessmentExpressAbi3,
+    verificationScope: {
+        ...assessmentExpressAbi3.verificationScope,
+        guidance: expressGuidance,
+    },
+};
+function scanResultWithAssessment(assessment, overrides = {}) {
+    return {
+        totalScore: 63,
+        layerScores: {
+            security: 10,
+            maintainability: 20,
+            ecosystem: 30,
+            upgradeImpact: 15,
+        },
+        findings: [],
+        generatedAt: "2026-01-01T00:00:00.000Z",
+        changedPackages: ["express"],
+        assessment,
+        decision: {
+            recommendation: "needs_review",
+            confidence: "high",
+            reasoning: ["Old generic decision reasoning — should not appear."],
+        },
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// projectReasoningLines — ABI 3 priority
+// ---------------------------------------------------------------------------
+describe("projectReasoningLines — ABI 3", () => {
+    it("returns assessment.reasoning when present (ABI 3 takes priority)", () => {
+        const result = scanResultWithAssessment(assessmentExpressAbi3);
+        const lines = projectReasoningLines(result);
+        expect(lines).toEqual(expressReasoning);
+    });
+    it("assessment.reasoning takes priority over decision.reasoning", () => {
+        const result = scanResultWithAssessment(assessmentExpressAbi3);
+        const lines = projectReasoningLines(result);
+        expect(lines).not.toContain("Old generic decision reasoning — should not appear.");
+    });
+    it("falls back to decision.reasoning when assessment.reasoning is empty", () => {
+        const assessmentWithoutReasoning = {
+            ...assessmentExpressAbi3,
+            reasoning: [],
+        };
+        const result = scanResultWithAssessment(assessmentWithoutReasoning);
+        const lines = projectReasoningLines(result);
+        expect(lines).toEqual([
+            "Old generic decision reasoning — should not appear.",
+        ]);
+    });
+    it("returns empty array when both reasoning sources are absent", () => {
+        const assessmentEmpty = {
+            ...assessmentExpressAbi3,
+            reasoning: [],
+        };
+        const result = scanResultWithAssessment(assessmentEmpty, {
+            decision: {
+                recommendation: "needs_review",
+                confidence: "high",
+                reasoning: [],
+            },
+        });
+        const lines = projectReasoningLines(result);
+        expect(lines).toEqual([]);
+    });
+    it("reasoning lines contain no prohibited vocabulary", () => {
+        const result = scanResultWithAssessment(assessmentExpressAbi3);
+        const lines = projectReasoningLines(result);
+        const joined = lines.join(" ");
+        const prohibited = [
+            "qualityClass",
+            "qualityBasis",
+            "proofFingerprint",
+            "observationId",
+            "propagationQualityRank",
+            "AssessmentEvidenceBundle",
+            "DenseEvidenceHighlight",
+            "will affect",
+            "will break",
+            "breaks compatibility",
+            "remain compatible",
+            "critical path",
+        ];
+        for (const term of prohibited) {
+            expect(joined).not.toContain(term);
+        }
+    });
+});
+// ---------------------------------------------------------------------------
+// projectVerificationActions — guidance priority
+// ---------------------------------------------------------------------------
+describe("projectVerificationActions — ABI 3 guidance", () => {
+    const presentation = toPublicPresentation(assessmentExpressAbi3WithGuidance.presentation);
+    it("returns guidance prose when verificationScope.guidance is present", () => {
+        const result = scanResultWithAssessment(assessmentExpressAbi3WithGuidance);
+        const actions = projectVerificationActions(assessmentExpressAbi3WithGuidance, presentation, result, 6);
+        expect(actions).toEqual(expressGuidance);
+    });
+    it("guidance respects max limit", () => {
+        const result = scanResultWithAssessment(assessmentExpressAbi3WithGuidance);
+        const actions = projectVerificationActions(assessmentExpressAbi3WithGuidance, presentation, result, 1);
+        expect(actions).toHaveLength(1);
+        expect(actions[0]).toBe(expressGuidance[0]);
+    });
+    it("falls back to focus tokens when guidance is absent", () => {
+        const result = scanResultWithAssessment(assessmentExpressAbi3);
+        const actions = projectVerificationActions(assessmentExpressAbi3, presentation, result, 6);
+        // No guidance — falls back to runtime focus tokens
+        expect(actions).toEqual(expect.arrayContaining(["routes", "middleware"]));
+    });
+    it("returns empty when verificationIntensity is none", () => {
+        const noneAssessment = {
+            ...assessmentExpressAbi3WithGuidance,
+            presentation: {
+                ...assessmentExpressAbi3WithGuidance.presentation,
+                verificationIntensity: "none",
+            },
+        };
+        const result = scanResultWithAssessment(noneAssessment);
+        const actions = projectVerificationActions(noneAssessment, toPublicPresentation(noneAssessment.presentation), result, 6);
+        expect(actions).toEqual([]);
+    });
+});
+// ---------------------------------------------------------------------------
+// PR comment — electionSummary and reasoning
+// ---------------------------------------------------------------------------
+describe("presentGitHubPrComment — ABI 3 expression", () => {
+    function buildBundle(assessment) {
+        const result = scanResultWithAssessment(assessment, {
+            changedPackages: ["express"],
+        });
+        return buildScanPresentationBundle({ result, pipelineStatus: "done" });
+    }
+    it("introLines include electionSummary when present", () => {
+        const bundle = buildBundle(assessmentExpressAbi3);
+        const comment = presentGitHubPrComment(bundle);
+        expect(comment.introLines).toContain(expressElectionSummary);
+    });
+    it("introLines include assessment.reasoning sentences", () => {
+        const bundle = buildBundle(assessmentExpressAbi3);
+        const comment = presentGitHubPrComment(bundle);
+        const joined = comment.introLines.join(" ");
+        expect(joined).toContain("express is used in HTTP request handling");
+        expect(joined).toContain("Import paths to application entry points");
+    });
+    it("electionSummary is absent from introLines when not set", () => {
+        const assessmentNoElection = {
+            ...assessmentExpressAbi3,
+            reviewFocalPoint: {
+                ...assessmentExpressAbi3.reviewFocalPoint,
+                electionSummary: undefined,
+            },
+        };
+        const bundle = buildBundle(assessmentNoElection);
+        const comment = presentGitHubPrComment(bundle);
+        expect(comment.introLines).not.toContain(expressElectionSummary);
+    });
+    it("introLines contain no prohibited vocabulary", () => {
+        const bundle = buildBundle(assessmentExpressAbi3);
+        const comment = presentGitHubPrComment(bundle);
+        const joined = comment.introLines.join(" ");
+        const prohibited = [
+            "qualityClass",
+            "qualityBasis",
+            "proofFingerprint",
+            "observationId",
+            "propagationQualityRank",
+        ];
+        for (const term of prohibited) {
+            expect(joined).not.toContain(term);
+        }
+    });
+});
+// ---------------------------------------------------------------------------
+// Check run — Why section uses assessment.reasoning
+// ---------------------------------------------------------------------------
+describe("presentGitHubCheckRun — ABI 3 Why section", () => {
+    const SCAN_ID = "scan-abi3-test";
+    const ORIGIN = "https://app.test";
+    function buildBundle(assessment) {
+        const result = scanResultWithAssessment(assessment, {
+            changedPackages: ["express"],
+        });
+        return buildScanPresentationBundle({ result, pipelineStatus: "done" });
+    }
+    it("Why section bullets come from assessment.reasoning (ABI 3)", () => {
+        const bundle = buildBundle(assessmentExpressAbi3);
+        const checkRun = presentGitHubCheckRun(bundle, {
+            scanId: SCAN_ID,
+            webAppOrigin: ORIGIN,
+        });
+        const whySection = checkRun.sections.find((s) => s.id === "why" && s.title === "Why");
+        expect(whySection).toBeDefined();
+        expect(whySection.bullets).toEqual(expect.arrayContaining([
+            "express is used in HTTP request handling in this repository via middleware chains.",
+        ]));
+    });
+    it("Why section does not contain old generic decision reasoning", () => {
+        const bundle = buildBundle(assessmentExpressAbi3);
+        const checkRun = presentGitHubCheckRun(bundle, {
+            scanId: SCAN_ID,
+            webAppOrigin: ORIGIN,
+        });
+        const whySection = checkRun.sections.find((s) => s.id === "why" && s.title === "Why");
+        const bulletText = whySection?.bullets.join(" ") ?? "";
+        expect(bulletText).not.toContain("Old generic decision reasoning");
+    });
+    it("check run summary contains no prohibited vocabulary", () => {
+        const result = scanResultWithAssessment(assessmentExpressAbi3, {
+            changedPackages: ["express"],
+            methodologyVersion: "mergesignal-engine/test",
+        });
+        const output = buildGitHubCheckRunOutput(result, {
+            scanId: SCAN_ID,
+            webAppOrigin: ORIGIN,
+        });
+        const prohibited = [
+            "qualityClass",
+            "qualityBasis",
+            "proofFingerprint",
+            "observationId",
+            "propagationQualityRank",
+            "AssessmentEvidenceBundle",
+        ];
+        for (const term of prohibited) {
+            expect(output.summary).not.toContain(term);
+        }
+    });
+    it("Why section respects 3-line limit", () => {
+        const bundle = buildBundle(assessmentExpressAbi3);
+        const checkRun = presentGitHubCheckRun(bundle, {
+            scanId: SCAN_ID,
+            webAppOrigin: ORIGIN,
+        });
+        const whySection = checkRun.sections.find((s) => s.title === "Why");
+        if (whySection) {
+            expect(whySection.bullets.length).toBeLessThanOrEqual(3);
+        }
+    });
+});
+// ---------------------------------------------------------------------------
+// End-to-end markdown snapshot — PR comment with ABI 3 fixture
+// ---------------------------------------------------------------------------
+describe("PR comment markdown — ABI 3 end-to-end", () => {
+    it("rendered markdown includes repository-specific reasoning", () => {
+        const result = scanResultWithAssessment(assessmentExpressAbi3, {
+            changedPackages: ["express"],
+        });
+        const markdown = presentGitHubPrCommentMarkdownFromResult(result);
+        expect(markdown).toContain("express is used in HTTP request handling");
+        expect(markdown).toContain("Import paths to application entry points");
+    });
+    it("rendered markdown includes electionSummary", () => {
+        const result = scanResultWithAssessment(assessmentExpressAbi3, {
+            changedPackages: ["express"],
+        });
+        const markdown = presentGitHubPrCommentMarkdownFromResult(result);
+        expect(markdown).toContain("express was selected as the primary review anchor");
+    });
+    it("rendered markdown contains no prohibited vocabulary", () => {
+        const result = scanResultWithAssessment(assessmentExpressAbi3, {
+            changedPackages: ["express"],
+        });
+        const markdown = presentGitHubPrCommentMarkdownFromResult(result);
+        const prohibited = [
+            "qualityClass",
+            "qualityBasis",
+            "proofFingerprint",
+            "observationId",
+            "propagationQualityRank",
+            "AssessmentEvidenceBundle",
+            "DenseEvidenceHighlight",
+        ];
+        for (const term of prohibited) {
+            expect(markdown).not.toContain(term);
+        }
+    });
+});

package/dist/presentation/presenters/presentGitHubCheckRun.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presentGitHubCheckRun.d.ts","sourceRoot":"","sources":["../../../src/presentation/presenters/presentGitHubCheckRun.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AACrF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AAGzF,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAChE,0BAA0B,CA4C5B"}
+{"version":3,"file":"presentGitHubCheckRun.d.ts","sourceRoot":"","sources":["../../../src/presentation/presenters/presentGitHubCheckRun.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AACrF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AAGzF,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAChE,0BAA0B,CAmD5B"}

package/dist/presentation/presenters/presentGitHubCheckRun.js

@@ -4,7 +4,7 @@ import { projectAssessmentFields } from "../projectAssessmentFields.js";
 export function presentGitHubCheckRun(bundle, ctx) {
     const { profile } = bundle;
     const headline = composeHeadline(bundle);
-    const keyPoints = projectCompactKeyPoints(buildNarrativeChannels(bundle), 3);
+    const assessmentFields = projectAssessmentFields(bundle);
     const actions = composeVerificationActions(bundle, 3);
     const detailsUrl = `${ctx.webAppOrigin.replace(/\/$/, "")}/scan/${ctx.scanId}`;
     const conclusion = profile.status === "safe"
@@ -22,15 +22,21 @@ export function presentGitHubCheckRun(bundle, ctx) {
             bullets: [`${prRiskScore} (${prRiskBandLabelText})`],
         });
     }
-    if (keyPoints.length > 0) {
-        sections.push({ id: "why", title: "Why", bullets: keyPoints });
+    // Use assessment.reasoning directly for the Why section (ABI 3).
+    // Fall back to compact key points for pre-ABI-3 scan results.
+    const reasoningLines = assessmentFields.reasoning.slice(0, 3);
+    const whyBullets = reasoningLines.length > 0
+        ? reasoningLines
+        : projectCompactKeyPoints(buildNarrativeChannels(bundle), 3);
+    if (whyBullets.length > 0) {
+        sections.push({ id: "why", title: "Why", bullets: whyBullets });
     }
     if (actions.length > 0) {
         sections.push({ id: "actions", title: "What to verify", bullets: actions });
     }
     sections.push({ id: "footer", bullets: [`Full scan: ${detailsUrl}`] });
     return {
-        ...projectAssessmentFields(bundle),
+        ...assessmentFields,
         status: profile.status,
         density: profile.density,
         confidence: profile.confidence,

package/dist/presentation/presenters/presentGitHubPrComment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presentGitHubPrComment.d.ts","sourceRoot":"","sources":["../../../src/presentation/presenters/presentGitHubPrComment.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACtF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AAGzF,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,sBAAsB,GAC7B,2BAA2B,CAmC7B"}
+{"version":3,"file":"presentGitHubPrComment.d.ts","sourceRoot":"","sources":["../../../src/presentation/presenters/presentGitHubPrComment.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACtF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AAGzF,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,sBAAsB,GAC7B,2BAA2B,CAqC7B"}

package/dist/presentation/presenters/presentGitHubPrComment.js

@@ -16,6 +16,9 @@ export function presentGitHubPrComment(bundle) {
     if (prRiskScore != null && prRiskBandLabelText) {
         introLines.push(`PR Risk: ${prRiskScore} (${prRiskBandLabelText})`);
     }
+    const electionSummary = bundle.assessment.reviewFocalPoint.electionSummary;
+    if (electionSummary)
+        introLines.push(electionSummary);
     for (const line of assessmentFields.reasoning.slice(0, 2)) {
         introLines.push(line);
     }

package/dist/scanResultSchema.d.ts

@@ -131,6 +131,7 @@ export declare const engineOutputScanResultSchema: z.ZodObject<{
                         concern: "concern";
                         reach: "reach";
                         changeSeverity: "changeSeverity";
+                        repository_importance: "repository_importance";
                         role_salience_tiebreak: "role_salience_tiebreak";
                     }>;
                     evidenceRefs: z.ZodArray<z.ZodString>;
@@ -142,11 +143,13 @@ export declare const engineOutputScanResultSchema: z.ZodObject<{
                         concern: "concern";
                         reach: "reach";
                         changeSeverity: "changeSeverity";
+                        repository_importance: "repository_importance";
                         role_salience_tiebreak: "role_salience_tiebreak";
                     }>;
                     evidenceRefs: z.ZodArray<z.ZodString>;
                 }, z.core.$strip>>;
             }, z.core.$strip>;
+            electionSummary: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
         reachScope: z.ZodObject<{
             packages: z.ZodArray<z.ZodString>;
@@ -161,6 +164,7 @@ export declare const engineOutputScanResultSchema: z.ZodObject<{
         verificationScope: z.ZodObject<{
             packages: z.ZodArray<z.ZodString>;
             focus: z.ZodArray<z.ZodString>;
+            guidance: z.ZodOptional<z.ZodArray<z.ZodString>>;
             artifactGrounded: z.ZodOptional<z.ZodObject<{
                 packages: z.ZodArray<z.ZodString>;
                 focus: z.ZodArray<z.ZodString>;
@@ -199,6 +203,7 @@ export declare const engineOutputScanResultSchema: z.ZodObject<{
             rank: z.ZodNumber;
             packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
             evidenceRefs: z.ZodArray<z.ZodString>;
+            context: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         factors: z.ZodArray<z.ZodString>;
         changeClasses: z.ZodArray<z.ZodEnum<{
@@ -238,6 +243,8 @@ export declare const engineOutputScanResultSchema: z.ZodObject<{
                 high_signal_pr: "high_signal_pr";
             }>;
         }, z.core.$strip>;
+        reasoning: z.ZodArray<z.ZodString>;
+        confidenceRationale: z.ZodString;
     }, z.core.$strip>;
     prRisk: z.ZodObject<{
         score: z.ZodNumber;

package/dist/scanResultSchema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanResultSchema.d.ts","sourceRoot":"","sources":["../src/scanResultSchema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtE,wGAAwG;AACxG,eAAO,MAAM,eAAe,EAAG,GAAY,CAAC;AAE5C,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,EAAG,GAAY,CAAC;AAmBnD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAc/D;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8Bb,CAAC;AAUjB;;;GAGG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMvC,CAAC;AAEH,MAAM,MAAM,kCAAkC,GAAG;IAC/C,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,kCAAkC,GAAG;IAC/C,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,uBAAuB,CAAC;CACjC,CAAC;AAEF,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,OAAO,GACZ,kCAAkC,GAAG,kCAAkC,CAezE;AAED,uFAAuF;AACvF,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,OAAO,GACZ,uBAAuB,CAMzB;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,UAAU,CAAC;CACpB,CAAC;AAEF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,GACZ,sBAAsB,GAAG,sBAAsB,CAajD;AAED,yEAAyE;AACzE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAMhE"}
+{"version":3,"file":"scanResultSchema.d.ts","sourceRoot":"","sources":["../src/scanResultSchema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtE,wGAAwG;AACxG,eAAO,MAAM,eAAe,EAAG,GAAY,CAAC;AAE5C,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,EAAG,GAAY,CAAC;AAmBnD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAc/D;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8Bb,CAAC;AAUjB;;;GAGG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMvC,CAAC;AAEH,MAAM,MAAM,kCAAkC,GAAG;IAC/C,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,kCAAkC,GAAG;IAC/C,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,uBAAuB,CAAC;CACjC,CAAC;AAEF,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,OAAO,GACZ,kCAAkC,GAAG,kCAAkC,CAezE;AAED,uFAAuF;AACvF,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,OAAO,GACZ,uBAAuB,CAMzB;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,UAAU,CAAC;CACpB,CAAC;AAEF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,GACZ,sBAAsB,GAAG,sBAAsB,CAajD;AAED,yEAAyE;AACzE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAMhE"}

package/dist/scanResultSchema.test.js

@@ -89,6 +89,8 @@ const minimalAssessment = {
     concerns: [],
     factors: ["tooling_maintenance"],
     changeClasses: ["tooling_maintenance"],
+    reasoning: [],
+    confidenceRationale: "",
     presentation: {
         narrativeIntensity: "minimal",
         reachVisibility: "hidden",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mergesignal/shared",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "MergeSignal shared scan contract, presentation policy, and trusted validation",
   "type": "module",
   "main": "./dist/index.js",