@unbrained/pm-cli 2026.9.5 → 2026.9.7

package/dist/sdk/governance/defect-recurrence-coverage.js

@@ -0,0 +1,189 @@
+/**
+ * @module sdk/governance/defect-recurrence-coverage
+ *
+ * Measures policy coverage against all recorded recurrence components and pages
+ * the uncovered evidence without allowing pagination to weaken the verdict.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ef2edfdc-7166-5cfc-adf1-fc8c69dfab1c")}catch(e){}}();
+import { createHash } from "node:crypto";
+import { stableStringify } from "../../core/shared/serialization.js";
+import { DEFECT_ESCAPE_CLASSES, parseDefectRecurrencePolicy, parseDefectChangeRiskRequest, } from "./defect-recurrence.js";
+import { buildDefectRecurrenceGraph, readDefectRecurrenceRecord, } from "./defect-recurrence-graph.js";
+/** Validate lineage-policy and paging input at the untrusted transport boundary. */
+export function parseDefectRecurrenceCoverageRequest(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError("recurrence coverage request must be an object");
+    }
+    const input = value;
+    if (Object.hasOwn(input, "change")) {
+        throw new TypeError("recurrence coverage request does not accept change");
+    }
+    if (input.uncoveredOnly !== undefined &&
+        typeof input.uncoveredOnly !== "boolean") {
+        throw new TypeError("recurrence coverage request.uncoveredOnly must be a boolean");
+    }
+    const { policy, cursor, limit } = parseDefectChangeRiskRequest({
+        ...input,
+        change: {},
+    });
+    return {
+        policy,
+        ...(cursor === undefined ? {} : { cursor }),
+        ...(limit === undefined ? {} : { limit }),
+        ...(input.uncoveredOnly === undefined
+            ? {}
+            : { uncoveredOnly: input.uncoveredOnly }),
+    };
+}
+/** Decode a cursor only when its evidence identity and safe integer offset match. */
+function coverageOffset(cursor, fingerprint) {
+    if (cursor === undefined)
+        return 0;
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new TypeError("recurrence coverage cursor is invalid");
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError("recurrence coverage cursor is invalid");
+    }
+    const record = value;
+    if (record.fingerprint !== fingerprint ||
+        typeof record.offset !== "number" ||
+        !Number.isSafeInteger(record.offset) ||
+        record.offset < 0) {
+        throw new TypeError("recurrence coverage cursor does not match this evidence and filter");
+    }
+    return record.offset;
+}
+/** Count the complete graph and hash its evidence before selecting any page. */
+function summarizeCoverage(graph, records, knownIds, ids, identity, uncoveredOnly) {
+    const classCounts = Object.fromEntries(DEFECT_ESCAPE_CLASSES.map((key) => [key, 0]));
+    let coveredCount = 0;
+    let uncoveredCount = 0;
+    let missingCount = 0;
+    let classifiedCount = 0;
+    const selected = [];
+    const hash = createHash("sha256").update(identity);
+    for (const id of ids) {
+        const lineage = graph.membership.get(id);
+        const present = knownIds.has(id);
+        const covered = lineage.family_ids.length > 0;
+        if (covered && present)
+            coveredCount += 1;
+        if (!covered)
+            uncoveredCount += 1;
+        if (!present)
+            missingCount += 1;
+        const classification = records.get(id)?.escape_class;
+        if (classification !== undefined &&
+            DEFECT_ESCAPE_CLASSES.includes(classification)) {
+            classCounts[classification] += 1;
+            classifiedCount += 1;
+        }
+        hash.update(stableStringify([
+            id,
+            present,
+            records.get(id) ?? null,
+            lineage.id,
+            lineage.family_ids,
+        ]));
+        if (!uncoveredOnly || !covered || !present)
+            selected.push(id);
+    }
+    return {
+        classCounts,
+        coveredCount,
+        uncoveredCount,
+        missingCount,
+        classifiedCount,
+        selected,
+        fingerprint: hash.digest("hex"),
+    };
+}
+/** Evaluate all local recurs_from lineages before applying any result-row limit. */
+export function analyzeDefectRecurrenceCoverage(policy, items, options = {}) {
+    parseDefectRecurrencePolicy(policy);
+    const limit = options.limit ?? 25;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
+        throw new TypeError("recurrence coverage limit must be an integer from 1 through 100");
+    }
+    const knownIds = new Set();
+    const records = new Map();
+    for (const item of items) {
+        if (knownIds.has(item.id))
+            throw new TypeError(`Duplicate recurrence item ${item.id}`);
+        knownIds.add(item.id);
+        const record = readDefectRecurrenceRecord(item);
+        if (record !== undefined)
+            records.set(item.id, record);
+    }
+    const graph = buildDefectRecurrenceGraph(policy.families, records);
+    const ids = [...graph.membership.keys()].sort();
+    const identity = stableStringify({
+        policy,
+        uncoveredOnly: options.uncoveredOnly === true,
+    });
+    const { classCounts, coveredCount, uncoveredCount, missingCount, classifiedCount, selected, fingerprint, } = summarizeCoverage(graph, records, knownIds, ids, identity, options.uncoveredOnly === true);
+    const offset = coverageOffset(options.cursor, fingerprint);
+    if (offset > selected.length)
+        throw new TypeError("recurrence coverage cursor offset exceeds the selected population");
+    const page = selected
+        .slice(offset, offset + limit)
+        .map((id) => {
+        const lineage = graph.membership.get(id);
+        const present = knownIds.has(id);
+        return {
+            item_id: id,
+            lineage_id: lineage.id,
+            lineage_item_count: lineage.item_ids.length,
+            family_ids: lineage.family_ids,
+            present,
+            ...(!present
+                ? { finding: "missing_recurrence_item" }
+                : lineage.family_ids.length === 0
+                    ? { finding: "unregistered_recurrence_item" }
+                    : {}),
+        };
+    });
+    const nextOffset = offset + page.length;
+    const lowerBound = ids.length === 0 ? null : classCounts.production_defect / ids.length;
+    return {
+        ok: uncoveredCount === 0 && missingCount === 0,
+        fingerprint,
+        items: page,
+        total: selected.length,
+        has_more: nextOffset < selected.length,
+        ...(nextOffset < selected.length
+            ? {
+                next_cursor: Buffer.from(JSON.stringify({ fingerprint, offset: nextOffset })).toString("base64url"),
+            }
+            : {}),
+        population: {
+            scope: "all_recorded_recurrence_items",
+            item_count: ids.length,
+            lineage_count: graph.lineages.length,
+            edge_count: graph.edge_count,
+            covered_item_count: coveredCount,
+            uncovered_item_count: uncoveredCount,
+            missing_item_count: missingCount,
+            classified_item_count: classifiedCount,
+            unclassified_item_count: ids.length - classifiedCount,
+            class_counts: classCounts,
+            escape_rate: classifiedCount === ids.length ? lowerBound : null,
+            escape_rate_lower_bound: lowerBound,
+        },
+        budget_scope: "registered_families_only",
+        cost: {
+            items_scanned: items.length,
+            edges_scanned: graph.edge_count,
+            row_limit: limit,
+        },
+        row_contract: { row_keys: ["items"], jq_selector: ".items[]" },
+    };
+}
+//# sourceMappingURL=defect-recurrence-coverage.js.map
+//# debugId=ef2edfdc-7166-5cfc-adf1-fc8c69dfab1c

package/dist/sdk/governance/defect-recurrence-graph.d.ts

@@ -0,0 +1,33 @@
+import type { AssuranceItemRecord } from "./assurance.js";
+import type { DefectRecurrenceFamily } from "./defect-recurrence.js";
+/** Sparse item evidence retained so incremental graph edits can be reversed. */
+export interface DefectRecurrenceRecord {
+    /** Unique local predecessors named by recurs_from edges. */
+    targets: string[];
+    /** Project file paths used as exact change-risk triggers after lineage registration. */
+    files: string[];
+    /** Recorded classification, never inferred from a registered family's label. */
+    escape_class?: string;
+}
+/** One weakly connected recurrence component, traversed without a depth ceiling. */
+export interface DefectRecurrenceLineage {
+    /** Lexically first member, used as a stable identifier for the current component. */
+    id: string;
+    /** Every member, in deterministic code-point order. */
+    item_ids: string[];
+    /** Families explicitly seeded anywhere in this component. */
+    family_ids: string[];
+}
+/** Complete sparse graph used internally by the bounded public coverage report. */
+export interface DefectRecurrenceGraph {
+    /** Components sorted by their current stable id. */
+    lineages: DefectRecurrenceLineage[];
+    /** Sparse lookup from every recurrence member to its component. */
+    membership: Map<string, DefectRecurrenceLineage>;
+    /** Number of distinct directed local recurrence edges. */
+    edge_count: number;
+}
+/** Read a sparse projection without retaining full item bodies or history. */
+export declare function readDefectRecurrenceRecord(item: AssuranceItemRecord): DefectRecurrenceRecord | undefined;
+/** Build iterative undirected connectivity from directed recurrence evidence. */
+export declare function buildDefectRecurrenceGraph(families: readonly DefectRecurrenceFamily[], records: ReadonlyMap<string, DefectRecurrenceRecord>): DefectRecurrenceGraph;

package/dist/sdk/governance/defect-recurrence-graph.js

@@ -0,0 +1,121 @@
+/**
+ * @module sdk/governance/defect-recurrence-graph
+ *
+ * Derives recurrence families from local recorded edges. Association, hierarchy,
+ * external references, and matching file globs never establish family coverage.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9d171110-2de0-5fa2-ae85-5a4e3ab4d46e")}catch(e){}}();
+import { isExternalDependencyReference, isExternalDependencySourceKind, } from "../../core/item/dependency-reference.js";
+/** Extract local recurrence targets while rejecting malformed and external edges. */
+function recurrenceTargets(item) {
+    const targets = new Set();
+    for (const edge of Array.isArray(item.dependencies)
+        ? item.dependencies
+        : []) {
+        if (typeof edge !== "object" || edge === null || Array.isArray(edge))
+            continue;
+        if (edge.kind !== "recurs_from")
+            continue;
+        if (typeof edge.id !== "string" || !edge.id.trim())
+            continue;
+        if (isExternalDependencyReference(edge.id) ||
+            isExternalDependencySourceKind(typeof edge.source_kind === "string" ? edge.source_kind : undefined))
+            continue;
+        targets.add(edge.id.trim());
+    }
+    return [...targets].sort();
+}
+/** Extract project-scoped exact file triggers from untrusted linked-file records. */
+function recurrenceFiles(item) {
+    const files = new Set();
+    for (const file of Array.isArray(item.files) ? item.files : []) {
+        if (typeof file !== "object" || file === null || Array.isArray(file))
+            continue;
+        const entry = file;
+        if (entry.scope !== undefined && entry.scope !== "project")
+            continue;
+        if (typeof entry.path === "string" && entry.path.trim())
+            files.add(entry.path.trim());
+    }
+    return [...files].sort();
+}
+/** Read a sparse projection without retaining full item bodies or history. */
+export function readDefectRecurrenceRecord(item) {
+    const targets = recurrenceTargets(item);
+    const files = recurrenceFiles(item);
+    const escapeClass = typeof item.escape_class === "string" ? item.escape_class : undefined;
+    if (targets.length === 0 && files.length === 0 && escapeClass === undefined)
+        return undefined;
+    return {
+        targets,
+        files,
+        ...(escapeClass === undefined ? {} : { escape_class: escapeClass }),
+    };
+}
+/** Traverse one component iteratively and collect only explicitly seeded families. */
+function traverseLineage(start, adjacency, seeds, membership) {
+    const lineage = {
+        id: start,
+        item_ids: [],
+        family_ids: [],
+    };
+    const pending = [start];
+    const familyIds = new Set();
+    membership.set(start, lineage);
+    while (pending.length > 0) {
+        const id = pending.pop();
+        lineage.item_ids.push(id);
+        for (const familyId of seeds.get(id) ?? [])
+            familyIds.add(familyId);
+        for (const target of adjacency.get(id)) {
+            if (membership.has(target))
+                continue;
+            membership.set(target, lineage);
+            pending.push(target);
+        }
+    }
+    lineage.item_ids.sort();
+    lineage.id = lineage.item_ids[0];
+    lineage.family_ids = [...familyIds].sort();
+    return lineage;
+}
+/** Build iterative undirected connectivity from directed recurrence evidence. */
+export function buildDefectRecurrenceGraph(families, records) {
+    const adjacency = new Map();
+    let edgeCount = 0;
+    for (const [id, record] of records) {
+        for (const target of new Set(record.targets)) {
+            const outgoing = adjacency.get(id) ?? new Set();
+            outgoing.add(target);
+            adjacency.set(id, outgoing);
+            const incoming = adjacency.get(target) ?? new Set();
+            incoming.add(id);
+            adjacency.set(target, incoming);
+            edgeCount += 1;
+        }
+    }
+    const seeds = new Map();
+    for (const family of families) {
+        for (const id of [
+            family.owner_item_id,
+            ...family.historical_item_ids,
+            ...(family.triggers.item_ids ?? []),
+        ]) {
+            const ids = seeds.get(id) ?? new Set();
+            ids.add(family.id);
+            seeds.set(id, ids);
+        }
+    }
+    const membership = new Map();
+    const lineages = [];
+    for (const start of adjacency.keys()) {
+        if (membership.has(start))
+            continue;
+        lineages.push(traverseLineage(start, adjacency, seeds, membership));
+    }
+    lineages.sort((left, right) => (left.id < right.id ? -1 : 1));
+    return { lineages, membership, edge_count: edgeCount };
+}
+//# sourceMappingURL=defect-recurrence-graph.js.map
+//# debugId=9d171110-2de0-5fa2-ae85-5a4e3ab4d46e

package/dist/sdk/governance/defect-recurrence.d.ts

@@ -1,4 +1,6 @@
 import type { AssuranceItemRecord } from "./assurance.js";
+import { type DefectRecurrenceRecord } from "./defect-recurrence-graph.js";
+export type { DefectRecurrenceRecord } from "./defect-recurrence-graph.js";
 /** Stable defect escape taxonomy used by project policy and PM metadata. */
 export declare const DEFECT_ESCAPE_CLASSES: readonly ["production_defect", "nightly_regression", "scanner_finding", "review_caught_late"];
 /** Evidence dispositions accepted by the fail-closed defect gate. */
@@ -117,6 +119,12 @@ export interface DefectRecurrenceIndex {
     families: DefectRecurrenceFamily[];
     /** Sparse PM item-to-family index. */
     item_families: Record<string, string[]>;
+    /** Direct signal matches retained separately so removing an edge removes inherited matches. */
+    direct_item_families?: Record<string, string[]>;
+    /** Sparse recurrence and linked-file evidence retained for incremental graph updates. */
+    recurrence_records?: Record<string, DefectRecurrenceRecord>;
+    /** Exact project file matches inherited from explicitly registered recurrence lineages. */
+    file_families?: Record<string, string[]>;
     /** Build-cost receipt. */
     build: {
         /** Items inspected during this build. */

package/dist/sdk/governance/defect-recurrence.js

@@ -5,10 +5,11 @@
  * explains which local and hosted checks a proposed change must run.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="59f5918f-108e-5cad-905b-7f690c3c4794")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e3a44417-3835-504e-9ccd-0fef674b437c")}catch(e){}}();
 import { createHash } from "node:crypto";
 import { stableStringify } from "../../core/shared/serialization.js";
 import { defectRecurrenceItemSignals } from "./defect-recurrence-signals.js";
+import { buildDefectRecurrenceGraph, readDefectRecurrenceRecord, } from "./defect-recurrence-graph.js";
 /** Stable defect escape taxonomy used by project policy and PM metadata. */
 export const DEFECT_ESCAPE_CLASSES = [
     "production_defect",
@@ -215,23 +216,22 @@ function exactReasons(family, input) {
     }
     return reasons;
 }
+/** Explain item-trigger matches from explicit policy IDs or inherited index membership. */
 function itemReasons(family, input, itemFamilies) {
     const directItemIds = new Set(family.triggers.item_ids ?? []);
-    return uniqueSorted(input.item_ids ?? []).flatMap((itemId) => directItemIds.has(itemId) || itemFamilies[itemId]?.includes(family.id)
+    return uniqueSorted(input.item_ids ?? []).flatMap((itemId) => directItemIds.has(itemId) ||
+        (Object.hasOwn(itemFamilies, itemId) &&
+            itemFamilies[itemId].includes(family.id))
         ? [{ signal: "item", value: itemId, matched: family.id }]
         : []);
 }
+/** Collect direct policy matches without sorting intermediate selection-only results. */
 function familyReasons(family, input, itemFamilies) {
-    const reasons = [
+    return [
         ...fileReasons(family, input),
         ...exactReasons(family, input),
         ...itemReasons(family, input, itemFamilies),
     ];
-    return reasons.sort((left, right) => left.signal !== right.signal
-        ? left.signal.localeCompare(right.signal)
-        : left.value !== right.value
-            ? left.value.localeCompare(right.value)
-            : left.matched.localeCompare(right.matched));
 }
 function readRiskCursorOffset(cursor, indexFingerprint) {
     if (!cursor)
@@ -263,6 +263,76 @@ function changeSignalCount(input) {
         input.error_codes,
     ].reduce((total, values) => total + (values?.length ?? 0), 0);
 }
+/** Apply registered lineage membership to item and exact linked-file risk triggers. */
+function inheritRecurrenceFamilies(families, recurrenceRecords, itemFamilies) {
+    const graph = buildDefectRecurrenceGraph(families, recurrenceRecords);
+    const fileFamilies = new Map();
+    for (const lineage of graph.lineages) {
+        if (lineage.family_ids.length === 0)
+            continue;
+        for (const id of lineage.item_ids) {
+            itemFamilies[id] = uniqueSorted([
+                ...(Object.hasOwn(itemFamilies, id) ? itemFamilies[id] : []),
+                ...lineage.family_ids,
+            ]);
+            for (const file of recurrenceRecords.get(id)?.files ?? []) {
+                const matched = fileFamilies.get(file) ?? new Set();
+                for (const familyId of lineage.family_ids)
+                    matched.add(familyId);
+                fileFamilies.set(file, matched);
+            }
+        }
+    }
+    return fileFamilies;
+}
+/** Refresh changed sparse records, deleting evidence no longer present on an item. */
+function refreshRecurrenceRecords(recurrenceRecords, items) {
+    for (const item of items) {
+        const record = readDefectRecurrenceRecord(item);
+        if (record === undefined)
+            recurrenceRecords.delete(item.id);
+        else
+            recurrenceRecords.set(item.id, record);
+    }
+}
+/** Compile exact identifier contributions once rather than expanding every family per item. */
+function compileDirectItemSeeds(families) {
+    const historical = new Map();
+    const triggers = new Map();
+    for (const family of families) {
+        for (const [index, ids] of [
+            [historical, family.historical_item_ids],
+            [triggers, family.triggers.item_ids ?? []],
+        ]) {
+            for (const id of ids) {
+                const matches = index.get(id) ?? new Set();
+                matches.add(family.id);
+                index.set(id, matches);
+            }
+        }
+    }
+    return { historical, triggers };
+}
+/** Match identifier-only items without allocating per-family explanation records. */
+function directItemMatches(item, families, seeds) {
+    const signals = defectRecurrenceItemSignals(item);
+    const hasContext = [
+        signals.files,
+        signals.package_names,
+        signals.tags,
+        signals.error_codes,
+    ].some((values) => values && values.length > 0);
+    if (hasContext) {
+        return families
+            .filter((family) => family.historical_item_ids.includes(item.id) ||
+            familyReasons(family, signals, {}).length > 0)
+            .map((family) => family.id);
+    }
+    return uniqueSorted([
+        ...(seeds.historical.get(item.id) ?? []),
+        ...(seeds.triggers.get(item.id.trim()) ?? []),
+    ]);
+}
 /** Compile deterministic policy and PM metadata into a sparse incremental index. */
 export function buildDefectRecurrenceIndex(policy, items, options = {}) {
     validatePolicy(policy);
@@ -270,21 +340,30 @@ export function buildDefectRecurrenceIndex(policy, items, options = {}) {
     const policyFingerprint = fingerprint({ ...policy, families });
     const changed = new Set(options.changed_item_ids ?? []);
     const canReuse = options.previous_index?.policy_fingerprint === policyFingerprint;
-    const itemFamilies = canReuse
-        ? Object.fromEntries(Object.entries(options.previous_index?.item_families ?? {}).filter(([itemId]) => !changed.has(itemId)))
-        : {};
+    const itemFamilies = Object.assign(Object.create(null), canReuse
+        ? Object.fromEntries(Object.entries(options.previous_index?.direct_item_families ??
+            options.previous_index?.item_families ??
+            {}).filter(([itemId]) => !changed.has(itemId)))
+        : {});
     const itemsReused = canReuse ? Object.keys(itemFamilies).length : 0;
+    const seeds = compileDirectItemSeeds(families);
     for (const item of items) {
-        const signals = defectRecurrenceItemSignals(item);
-        const matched = families
-            .filter((family) => family.historical_item_ids.includes(item.id) ||
-            familyReasons(family, signals, {}).length > 0)
-            .map((family) => family.id);
+        const matched = directItemMatches(item, families, seeds);
         if (matched.length > 0)
             itemFamilies[item.id] = matched;
         else
             delete itemFamilies[item.id];
     }
+    const directItemFamilies = Object.fromEntries(Object.entries(itemFamilies).sort(([left], [right]) => left < right ? -1 : 1));
+    const recurrenceRecords = new Map(canReuse
+        ? Object.entries(options.previous_index?.recurrence_records ?? {}).filter(([id]) => !changed.has(id))
+        : []);
+    refreshRecurrenceRecords(recurrenceRecords, items);
+    const fileFamilies = inheritRecurrenceFamilies(families, recurrenceRecords, itemFamilies);
+    const sortedRecords = Object.fromEntries([...recurrenceRecords].sort(([left], [right]) => (left < right ? -1 : 1)));
+    const sortedFileFamilies = Object.fromEntries([...fileFamilies]
+        .sort(([left], [right]) => (left < right ? -1 : 1))
+        .map(([file, matches]) => [file, [...matches].sort()]));
     const sortedItemFamilies = Object.fromEntries(Object.entries(itemFamilies)
         .sort(([left], [right]) => (left < right ? -1 : 1))
         .map(([itemId, familyIds]) => [itemId, uniqueSorted(familyIds)]));
@@ -294,9 +373,15 @@ export function buildDefectRecurrenceIndex(policy, items, options = {}) {
         index_fingerprint: fingerprint({
             policy_fingerprint: policyFingerprint,
             item_families: sortedItemFamilies,
+            direct_item_families: directItemFamilies,
+            recurrence_records: sortedRecords,
+            file_families: sortedFileFamilies,
         }),
         families,
         item_families: sortedItemFamilies,
+        direct_item_families: directItemFamilies,
+        recurrence_records: sortedRecords,
+        file_families: sortedFileFamilies,
         build: {
             items_scanned: items.length,
             items_reused: itemsReused,
@@ -313,6 +398,22 @@ export function analyzeDefectChangeRisk(index, input, options = {}) {
     const offset = readRiskCursorOffset(options.cursor, index.index_fingerprint);
     const matches = index.families.flatMap((family) => {
         const reasons = familyReasons(family, input, index.item_families);
+        for (const file of uniqueSorted(input.files ?? [])) {
+            if (index.file_families &&
+                Object.hasOwn(index.file_families, file) &&
+                index.file_families[file].includes(family.id)) {
+                reasons.push({
+                    signal: "file",
+                    value: file,
+                    matched: `recurs_from:${family.id}`,
+                });
+            }
+        }
+        reasons.sort((left, right) => left.signal !== right.signal
+            ? left.signal.localeCompare(right.signal)
+            : left.value !== right.value
+                ? left.value.localeCompare(right.value)
+                : left.matched.localeCompare(right.matched));
         return reasons.length === 0
             ? []
             : [
@@ -520,4 +621,4 @@ export function parseDefectChangeRiskRequest(value) {
     };
 }
 //# sourceMappingURL=defect-recurrence.js.map
-//# debugId=59f5918f-108e-5cad-905b-7f690c3c4794
+//# debugId=e3a44417-3835-504e-9ccd-0fef674b437c

package/dist/sdk/governance/health.d.ts

@@ -16,7 +16,7 @@ export interface HealthCheck {
     name: "settings" | "directories" | "settings_values" | "telemetry" | "extensions" | "storage" | "locks" | "integrity" | "history_drift" | "vectorization";
     /** Lifecycle state reported for status. */
     status: HealthStatus;
-    /** Boolean companion to status for direct agent and assurance predicates. */
+    /** True when this check has no gate-failing findings; advisory warnings retain warn status. */
     ok: boolean;
     /** Value that configures or reports details for this contract. */
     details: Record<string, unknown>;
@@ -40,6 +40,17 @@ export interface HealthFinding {
 export interface HealthResult {
     /** Whether the operation completed without a blocking failure. */
     ok: boolean;
+    /** Invocation policy and process outcome; `ok` is the authoritative health predicate. */
+    verdict?: {
+        /** Field consumers must branch on to decide project health. */
+        authority: "ok";
+        /** Present when a failed verdict sets a nonzero process exit; omitted means false. */
+        strict_exit?: true;
+        /** Present when missing merge drivers block this invocation; omitted means false. */
+        require_merge_drivers?: true;
+        /** Process exit code for this invocation, independent of diagnostic severity. */
+        exit_code: number;
+    };
     /** Value that configures or reports checks for this contract. */
     checks: HealthCheck[];
     /** Number of warning entries represented by this result. */
@@ -67,6 +78,10 @@ export interface HealthResult {
 }
 /** Documents the run health options payload exchanged by command, SDK, and package integrations. */
 export interface RunHealthOptions {
+    /** Match CLI strict-exit policy: require merge drivers and exit nonzero on blocking findings. */
+    strictExit?: boolean;
+    /** Compatibility alias for strictExit across SDK and MCP invocations. */
+    failOnWarn?: boolean;
     /** Value that configures or reports strict directories for this contract. */
     strictDirectories?: boolean;
     /** Treat absent clone-local merge drivers as a required health failure instead of an advisory. */
@@ -85,7 +100,7 @@ export interface RunHealthOptions {
     verboseAuthorEvents?: boolean;
     /** Value that configures or reports skip vectors for this contract. */
     skipVectors?: boolean;
-    /** Value that configures or reports skip integrity for this contract. */
+    /** Skip optional integrity work; full output and required merge-driver enforcement still run it. */
     skipIntegrity?: boolean;
     /** Value that configures or reports skip drift for this contract. */
     skipDrift?: boolean;