auditor-lambda 0.3.12 → 0.3.14

package/dist/orchestrator/reviewPackets.js

@@ -4,6 +4,48 @@ const DEFAULT_MAX_TASKS_PER_PACKET = 0;
 const DEFAULT_TARGET_PACKET_LINES = 8000;
 const ESTIMATED_TOKENS_PER_LINE = 4;
 const ESTIMATED_PACKET_PROMPT_TOKENS = 900;
+const PACKET_EXPANSION_MIN_CONFIDENCE = 0.65;
+const HIGH_FAN_DEGREE_THRESHOLD = 12;
+const HIGH_FAN_EXPANSION_CONFIDENCE = 0.99;
+const MAX_PACKET_KEY_EDGES = 8;
+const MAX_PACKET_BOUNDARY_FILES = 12;
+const MAX_WEAK_PACKET_SAMPLES = 12;
+const MAX_WEAK_PACKET_SAMPLE_FILES = 8;
+const WEAK_PACKET_GAP_ORDER = [
+    "missing_internal_edges",
+    "unexplained_files",
+    "partial_cohesion",
+];
+const MAX_ENTRYPOINT_FLOW_BRIDGE_HOPS = 3;
+const MAX_ENTRYPOINT_FLOW_BRANCHES = 8;
+const SUBSYSTEM_CLUSTER_CONFIDENCE = 0.7;
+const PACKAGE_OWNERSHIP_CLUSTER_CONFIDENCE = 0.68;
+const MODULE_OWNERSHIP_CLUSTER_CONFIDENCE = 0.66;
+const ANALYZER_OWNERSHIP_EDGE_KIND = "analyzer-ownership-root-link";
+const MAX_SUBSYSTEM_CLUSTER_GROUPS = 4;
+const MAX_SUBSYSTEM_CLUSTER_TASKS = 8;
+const MAX_SUBSYSTEM_CLUSTER_FILES = 8;
+const MODULE_OWNERSHIP_EDGE_KINDS = new Set([
+    "typescript-project-reference-link",
+    "go-workspace-module-link",
+    "cargo-workspace-member-link",
+    "maven-module-link",
+    ANALYZER_OWNERSHIP_EDGE_KIND,
+]);
+const BROAD_ANALYZER_OWNERSHIP_ROOTS = new Set([
+    "src",
+    "lib",
+    "app",
+    "apps",
+    "packages",
+    "services",
+    "crates",
+    "modules",
+    "test",
+    "tests",
+    "spec",
+    "specs",
+]);
 function priorityRank(priority) {
     switch (priority) {
         case "high":
@@ -36,6 +78,16 @@ function packetGroupingKey(task) {
     const scope = criticalFlowTag ?? task.unit_id;
     return `${scope}\0${taskFileSignature(task)}`;
 }
+function buildTaskGroups(tasks) {
+    const groups = new Map();
+    for (const task of tasks) {
+        const key = packetGroupingKey(task);
+        const group = groups.get(key) ?? [];
+        group.push(task);
+        groups.set(key, group);
+    }
+    return groups;
+}
 function normalizeGraphPath(path) {
     return path.replace(/\\/g, "/").replace(/^\.\//, "").toLowerCase();
 }
@@ -59,18 +111,680 @@ function collectGraphEdges(graphBundle) {
             if (typeof item.from !== "string" || typeof item.to !== "string") {
                 continue;
             }
-            edges.push({
+            const edge = {
                 from: item.from,
                 to: item.to,
                 kind: typeof item.kind === "string" ? item.kind : undefined,
-            });
+            };
+            if (item.direction === "directed" || item.direction === "undirected") {
+                edge.direction = item.direction;
+            }
+            if (typeof item.confidence === "number" && Number.isFinite(item.confidence)) {
+                edge.confidence = Math.min(1, Math.max(0, item.confidence));
+            }
+            if (typeof item.reason === "string" && item.reason.trim().length > 0) {
+                edge.reason = item.reason.trim();
+            }
+            edges.push(edge);
         }
     }
     return edges;
 }
-function isPacketExpansionEdge(edge) {
+function graphEdgeConfidence(edge) {
+    if (typeof edge.confidence === "number" && Number.isFinite(edge.confidence)) {
+        return Math.min(1, Math.max(0, edge.confidence));
+    }
+    if (edge.kind === "heuristic-container-edge") {
+        return 0.25;
+    }
+    if (edge.kind?.startsWith("heuristic-")) {
+        return 0.5;
+    }
+    return 0.8;
+}
+function isConcreteGraphEdge(edge) {
     return edge.kind !== "heuristic-container-edge";
 }
+function buildGraphDegreeIndex(edges) {
+    const fanIn = new Map();
+    const fanOut = new Map();
+    for (const edge of edges) {
+        if (!isConcreteGraphEdge(edge)) {
+            continue;
+        }
+        const from = normalizeGraphPath(edge.from);
+        const to = normalizeGraphPath(edge.to);
+        fanOut.set(from, (fanOut.get(from) ?? 0) + 1);
+        fanIn.set(to, (fanIn.get(to) ?? 0) + 1);
+    }
+    return { fanIn, fanOut };
+}
+function isPacketExpansionEdge(edge, degreeIndex) {
+    if (!isConcreteGraphEdge(edge)) {
+        return false;
+    }
+    const confidence = graphEdgeConfidence(edge);
+    if (confidence < PACKET_EXPANSION_MIN_CONFIDENCE) {
+        return false;
+    }
+    const fromFanOut = degreeIndex.fanOut.get(normalizeGraphPath(edge.from)) ?? 0;
+    const toFanIn = degreeIndex.fanIn.get(normalizeGraphPath(edge.to)) ?? 0;
+    const highFanEdge = fromFanOut > HIGH_FAN_DEGREE_THRESHOLD ||
+        toFanIn > HIGH_FAN_DEGREE_THRESHOLD;
+    return !highFanEdge || confidence >= HIGH_FAN_EXPANSION_CONFIDENCE;
+}
+function buildFileToGroupKeys(groups) {
+    const fileToGroupKeys = new Map();
+    for (const [key, tasks] of groups) {
+        for (const path of new Set(tasks.flatMap((task) => task.file_paths))) {
+            const normalized = normalizeGraphPath(path);
+            const existing = fileToGroupKeys.get(normalized) ?? new Set();
+            existing.add(key);
+            fileToGroupKeys.set(normalized, existing);
+        }
+    }
+    return fileToGroupKeys;
+}
+function collectEntrypointFlowRoots(graphEdges, graphBundle) {
+    const roots = new Set();
+    const routes = Array.isArray(graphBundle?.graphs.routes)
+        ? graphBundle.graphs.routes
+        : [];
+    for (const route of routes) {
+        if (isRecord(route) && typeof route.handler === "string") {
+            roots.add(normalizeGraphPath(route.handler));
+        }
+    }
+    for (const edge of graphEdges) {
+        if (edge.kind === "route-handler-link") {
+            roots.add(normalizeGraphPath(edge.from));
+            roots.add(normalizeGraphPath(edge.to));
+        }
+        else if (edge.kind === "package-entrypoint-link") {
+            roots.add(normalizeGraphPath(edge.to));
+        }
+    }
+    return roots;
+}
+function buildRepresentativePathIndex(groups, graphEdges, graphBundle) {
+    const representatives = new Map();
+    const addPath = (path) => {
+        const normalized = normalizeGraphPath(path);
+        if (!representatives.has(normalized)) {
+            representatives.set(normalized, path);
+        }
+    };
+    for (const tasks of groups.values()) {
+        for (const path of tasks.flatMap((task) => task.file_paths)) {
+            addPath(path);
+        }
+    }
+    for (const edge of graphEdges) {
+        addPath(edge.from);
+        addPath(edge.to);
+    }
+    const routes = Array.isArray(graphBundle?.graphs.routes)
+        ? graphBundle.graphs.routes
+        : [];
+    for (const route of routes) {
+        if (isRecord(route) && typeof route.handler === "string") {
+            addPath(route.handler);
+        }
+    }
+    return representatives;
+}
+function uniqueTaskFilePaths(tasks) {
+    return [...new Set(tasks.flatMap((task) => task.file_paths))].sort((a, b) => a.localeCompare(b));
+}
+function groupsOverlap(a, b) {
+    for (const key of a) {
+        if (b.has(key)) {
+            return true;
+        }
+    }
+    return false;
+}
+function buildGraphConnectedComponentIndex(groups, graphEdges) {
+    const groupKeys = [...groups.keys()];
+    const parent = new Map(groupKeys.map((key) => [key, key]));
+    const fileToGroupKeys = buildFileToGroupKeys(groups);
+    const degreeIndex = buildGraphDegreeIndex(graphEdges);
+    function find(key) {
+        const current = parent.get(key) ?? key;
+        if (current === key)
+            return key;
+        const root = find(current);
+        parent.set(key, root);
+        return root;
+    }
+    function union(a, b) {
+        const rootA = find(a);
+        const rootB = find(b);
+        if (rootA === rootB)
+            return;
+        const [keep, move] = rootA.localeCompare(rootB) <= 0 ? [rootA, rootB] : [rootB, rootA];
+        parent.set(move, keep);
+    }
+    for (const keys of fileToGroupKeys.values()) {
+        const [first, ...rest] = [...keys].sort((a, b) => a.localeCompare(b));
+        if (!first)
+            continue;
+        for (const key of rest) {
+            union(first, key);
+        }
+    }
+    for (const edge of graphEdges) {
+        if (!isPacketExpansionEdge(edge, degreeIndex)) {
+            continue;
+        }
+        const fromGroups = fileToGroupKeys.get(normalizeGraphPath(edge.from));
+        const toGroups = fileToGroupKeys.get(normalizeGraphPath(edge.to));
+        if (!fromGroups || !toGroups) {
+            continue;
+        }
+        for (const fromKey of fromGroups) {
+            for (const toKey of toGroups) {
+                union(fromKey, toKey);
+            }
+        }
+    }
+    return new Map(groupKeys.map((key) => [key, find(key)]));
+}
+function subsystemRootForPath(path) {
+    const segments = normalizeGraphPath(path).split("/").filter(Boolean);
+    const directories = segments.slice(0, -1);
+    if (directories.length < 2) {
+        return undefined;
+    }
+    const namespace = directories[0];
+    const depth = namespace === "apps" || namespace === "packages"
+        ? 4
+        : namespace === "src" ||
+            namespace === "lib" ||
+            namespace === "app" ||
+            namespace === "tests" ||
+            namespace === "test" ||
+            namespace === "spec"
+            ? 3
+            : 2;
+    if (directories.length < depth) {
+        return undefined;
+    }
+    return directories.slice(0, depth).join("/");
+}
+function subsystemRootForTasks(tasks) {
+    const rootsForFiles = uniqueTaskFilePaths(tasks).map(subsystemRootForPath);
+    if (rootsForFiles.some((root) => root === undefined)) {
+        return undefined;
+    }
+    const roots = new Set(rootsForFiles);
+    return roots.size === 1 ? [...roots][0] : undefined;
+}
+function buildBoundedClusterEdges(params) {
+    const groupToComponent = buildGraphConnectedComponentIndex(params.groups, params.graphEdges);
+    const clusters = new Map();
+    for (const [key, tasks] of params.groups) {
+        const root = params.rootForTasks(tasks);
+        if (!root) {
+            continue;
+        }
+        const filePaths = uniqueTaskFilePaths(tasks);
+        const cluster = clusters.get(root) ?? [];
+        cluster.push({
+            component: groupToComponent.get(key) ?? key,
+            tasks,
+            filePaths,
+            representativePath: filePaths[0] ?? root,
+        });
+        clusters.set(root, cluster);
+    }
+    const clusterEdges = [];
+    for (const [root, entries] of [...clusters.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        const components = new Map();
+        for (const entry of entries) {
+            const component = components.get(entry.component) ?? {
+                taskCount: 0,
+                filePaths: new Set(),
+                representativePath: entry.representativePath,
+            };
+            component.taskCount += entry.tasks.length;
+            for (const filePath of entry.filePaths) {
+                component.filePaths.add(filePath);
+            }
+            if (entry.representativePath.localeCompare(component.representativePath) < 0) {
+                component.representativePath = entry.representativePath;
+            }
+            components.set(entry.component, component);
+        }
+        const componentEntries = [...components.values()].sort((a, b) => a.representativePath.localeCompare(b.representativePath));
+        if (componentEntries.length < 2 ||
+            componentEntries.length > MAX_SUBSYSTEM_CLUSTER_GROUPS) {
+            continue;
+        }
+        const allFiles = new Set(componentEntries.flatMap((entry) => [...entry.filePaths]));
+        const totalTasks = componentEntries.reduce((sum, entry) => sum + entry.taskCount, 0);
+        const clusterTasks = entries.flatMap((entry) => entry.tasks);
+        const totalLines = [...allFiles].reduce((sum, path) => {
+            const owner = clusterTasks.find((task) => task.file_paths.includes(path));
+            return sum + (owner ? lineCountForPath(owner, path, params.lineIndex) : 0);
+        }, 0);
+        if (allFiles.size > MAX_SUBSYSTEM_CLUSTER_FILES ||
+            totalTasks > MAX_SUBSYSTEM_CLUSTER_TASKS ||
+            totalLines > (params.targetPacketLines ?? DEFAULT_TARGET_PACKET_LINES)) {
+            continue;
+        }
+        for (let index = 1; index < componentEntries.length; index++) {
+            const previous = componentEntries[index - 1];
+            const current = componentEntries[index];
+            clusterEdges.push({
+                from: previous.representativePath,
+                to: current.representativePath,
+                kind: params.edgeKind,
+                direction: "undirected",
+                confidence: params.edgeConfidence,
+                reason: params.reasonForCluster(root, allFiles.size),
+            });
+        }
+    }
+    return clusterEdges.sort(compareGraphEdges);
+}
+function buildSubsystemClusterEdges(groups, graphEdges, lineIndex, targetPacketLines = DEFAULT_TARGET_PACKET_LINES) {
+    return buildBoundedClusterEdges({
+        groups,
+        graphEdges,
+        rootForTasks: subsystemRootForTasks,
+        edgeKind: "subsystem-cluster-link",
+        edgeConfidence: SUBSYSTEM_CLUSTER_CONFIDENCE,
+        reasonForCluster: (root, fileCount) => `Bounded subsystem cluster '${root}' groups ${fileCount} file(s) without stronger graph evidence.`,
+        lineIndex,
+        targetPacketLines,
+    });
+}
+function packageManifestRoot(path) {
+    const segments = normalizeGraphPath(path).split("/").filter(Boolean);
+    if (segments.at(-1) !== "package.json" || segments.length < 2) {
+        return undefined;
+    }
+    return segments.slice(0, -1).join("/");
+}
+function isTypescriptProjectConfigPath(path) {
+    const basename = normalizeGraphPath(path).split("/").at(-1);
+    if (!basename) {
+        return false;
+    }
+    return (basename === "tsconfig.json" ||
+        (basename.startsWith("tsconfig.") && basename.endsWith(".json")));
+}
+function isGoModuleManifestPath(path) {
+    return normalizeGraphPath(path).split("/").at(-1) === "go.mod";
+}
+function isCargoManifestPath(path) {
+    return normalizeGraphPath(path).split("/").at(-1) === "cargo.toml";
+}
+function isMavenPomPath(path) {
+    return normalizeGraphPath(path).split("/").at(-1) === "pom.xml";
+}
+function typescriptProjectRoot(path) {
+    const segments = normalizeGraphPath(path).split("/").filter(Boolean);
+    if (!isTypescriptProjectConfigPath(path) || segments.length < 2) {
+        return undefined;
+    }
+    return segments.slice(0, -1).join("/");
+}
+function goModuleRoot(path) {
+    const segments = normalizeGraphPath(path).split("/").filter(Boolean);
+    if (!isGoModuleManifestPath(path) || segments.length < 2) {
+        return undefined;
+    }
+    return segments.slice(0, -1).join("/");
+}
+function cargoModuleRoot(path) {
+    const segments = normalizeGraphPath(path).split("/").filter(Boolean);
+    if (!isCargoManifestPath(path) || segments.length < 2) {
+        return undefined;
+    }
+    return segments.slice(0, -1).join("/");
+}
+function mavenModuleRoot(path) {
+    const segments = normalizeGraphPath(path).split("/").filter(Boolean);
+    if (!isMavenPomPath(path) || segments.length < 2) {
+        return undefined;
+    }
+    return segments.slice(0, -1).join("/");
+}
+function moduleConfigRoot(path) {
+    return (typescriptProjectRoot(path) ??
+        goModuleRoot(path) ??
+        cargoModuleRoot(path) ??
+        mavenModuleRoot(path));
+}
+function analyzerOwnershipRoot(path) {
+    const root = normalizeGraphPath(path).replace(/\/+$/, "");
+    if (root.length === 0 ||
+        root === "." ||
+        root === ".." ||
+        root.startsWith("../") ||
+        root.startsWith("/")) {
+        return undefined;
+    }
+    const segments = root.split("/").filter(Boolean);
+    if (segments.length === 1 &&
+        BROAD_ANALYZER_OWNERSHIP_ROOTS.has(segments[0])) {
+        return undefined;
+    }
+    return root;
+}
+function collectPackageOwnershipRoots(groups, graphEdges) {
+    const roots = new Set();
+    const addRoot = (path) => {
+        const root = packageManifestRoot(path);
+        if (root) {
+            roots.add(root);
+        }
+    };
+    for (const tasks of groups.values()) {
+        for (const path of tasks.flatMap((task) => task.file_paths)) {
+            addRoot(path);
+        }
+    }
+    for (const edge of graphEdges) {
+        addRoot(edge.from);
+        addRoot(edge.to);
+    }
+    return roots;
+}
+function ownershipRootForPath(path, ownershipRoots) {
+    const normalized = normalizeGraphPath(path);
+    let bestMatch;
+    for (const root of ownershipRoots) {
+        if (normalized === `${root}/package.json` ||
+            normalized === `${root}/tsconfig.json` ||
+            normalized.startsWith(`${root}/`)) {
+            if (!bestMatch || root.length > bestMatch.length) {
+                bestMatch = root;
+            }
+        }
+    }
+    return bestMatch;
+}
+function packageOwnershipRootForTasks(tasks, packageRoots) {
+    if (packageRoots.size === 0) {
+        return undefined;
+    }
+    const rootsForFiles = uniqueTaskFilePaths(tasks).map((path) => ownershipRootForPath(path, packageRoots));
+    if (rootsForFiles.some((root) => root === undefined)) {
+        return undefined;
+    }
+    const roots = new Set(rootsForFiles);
+    return roots.size === 1 ? [...roots][0] : undefined;
+}
+function buildPackageOwnershipClusterEdges(groups, graphEdges, lineIndex, targetPacketLines = DEFAULT_TARGET_PACKET_LINES) {
+    const packageRoots = collectPackageOwnershipRoots(groups, graphEdges);
+    if (packageRoots.size === 0) {
+        return [];
+    }
+    return buildBoundedClusterEdges({
+        groups,
+        graphEdges,
+        rootForTasks: (tasks) => packageOwnershipRootForTasks(tasks, packageRoots),
+        edgeKind: "package-ownership-link",
+        edgeConfidence: PACKAGE_OWNERSHIP_CLUSTER_CONFIDENCE,
+        reasonForCluster: (root, fileCount) => `Package ownership root '${root}' groups ${fileCount} file(s) across bounded package subdirectories.`,
+        lineIndex,
+        targetPacketLines,
+    });
+}
+function collectModuleOwnershipRoots(groups, graphEdges) {
+    const roots = new Map();
+    const addRoot = (path) => {
+        const root = moduleConfigRoot(path);
+        if (root) {
+            roots.set(root, roots.get(root) ?? "project configuration");
+        }
+    };
+    const addAnalyzerRoot = (path) => {
+        const root = analyzerOwnershipRoot(path);
+        if (root) {
+            roots.set(root, roots.get(root) ?? "analyzer ownership hint");
+        }
+    };
+    for (const tasks of groups.values()) {
+        for (const path of tasks.flatMap((task) => task.file_paths)) {
+            addRoot(path);
+        }
+    }
+    for (const edge of graphEdges) {
+        if (edge.kind === ANALYZER_OWNERSHIP_EDGE_KIND) {
+            addAnalyzerRoot(edge.from);
+            continue;
+        }
+        if (!MODULE_OWNERSHIP_EDGE_KINDS.has(edge.kind ?? "")) {
+            continue;
+        }
+        addRoot(edge.from);
+        addRoot(edge.to);
+    }
+    return roots;
+}
+function moduleOwnershipRootForTasks(tasks, moduleRoots) {
+    if (moduleRoots.size === 0) {
+        return undefined;
+    }
+    const rootsForFiles = uniqueTaskFilePaths(tasks).map((path) => ownershipRootForPath(path, moduleRoots));
+    if (rootsForFiles.some((root) => root === undefined)) {
+        return undefined;
+    }
+    const roots = new Set(rootsForFiles);
+    return roots.size === 1 ? [...roots][0] : undefined;
+}
+function buildModuleOwnershipClusterEdges(groups, graphEdges, lineIndex, targetPacketLines = DEFAULT_TARGET_PACKET_LINES) {
+    const moduleRoots = collectModuleOwnershipRoots(groups, graphEdges);
+    if (moduleRoots.size === 0) {
+        return [];
+    }
+    const moduleRootSet = new Set(moduleRoots.keys());
+    return buildBoundedClusterEdges({
+        groups,
+        graphEdges,
+        rootForTasks: (tasks) => moduleOwnershipRootForTasks(tasks, moduleRootSet),
+        edgeKind: "module-ownership-link",
+        edgeConfidence: MODULE_OWNERSHIP_CLUSTER_CONFIDENCE,
+        reasonForCluster: (root, fileCount) => {
+            const source = moduleRoots.get(root) ?? "project configuration";
+            return source === "analyzer ownership hint"
+                ? `Module ownership root '${root}' from analyzer ownership hint groups ${fileCount} file(s) across bounded subdirectories.`
+                : `Module ownership root '${root}' from project configuration groups ${fileCount} file(s) across bounded subdirectories.`;
+        },
+        lineIndex,
+        targetPacketLines,
+    });
+}
+function buildEntrypointFlowBridgeEdges(groups, graphEdges, graphBundle) {
+    const roots = collectEntrypointFlowRoots(graphEdges, graphBundle);
+    if (roots.size === 0) {
+        return [];
+    }
+    const fileToGroupKeys = buildFileToGroupKeys(groups);
+    const degreeIndex = buildGraphDegreeIndex(graphEdges);
+    const representatives = buildRepresentativePathIndex(groups, graphEdges, graphBundle);
+    const adjacency = new Map();
+    for (const edge of graphEdges) {
+        if (edge.direction === "undirected" ||
+            !isPacketExpansionEdge(edge, degreeIndex)) {
+            continue;
+        }
+        const from = normalizeGraphPath(edge.from);
+        const edges = adjacency.get(from) ?? [];
+        edges.push(edge);
+        adjacency.set(from, edges);
+    }
+    for (const edges of adjacency.values()) {
+        edges.sort(compareGraphEdges);
+    }
+    const bridgeEdges = new Map();
+    const displayPath = (normalized) => representatives.get(normalized) ?? normalized;
+    for (const root of [...roots].sort((a, b) => a.localeCompare(b))) {
+        const rootGroups = fileToGroupKeys.get(root);
+        if (!rootGroups) {
+            continue;
+        }
+        const queue = [
+            { node: root, path: [root], edges: [] },
+        ];
+        const visited = new Set([root]);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (!current || current.edges.length >= MAX_ENTRYPOINT_FLOW_BRIDGE_HOPS) {
+                continue;
+            }
+            const outgoing = adjacency.get(current.node) ?? [];
+            if (outgoing.length > MAX_ENTRYPOINT_FLOW_BRANCHES) {
+                continue;
+            }
+            for (const edge of outgoing) {
+                const target = normalizeGraphPath(edge.to);
+                if (current.path.includes(target)) {
+                    continue;
+                }
+                const nextEdges = [...current.edges, edge];
+                const nextPath = [...current.path, target];
+                const targetGroups = fileToGroupKeys.get(target);
+                if (targetGroups &&
+                    nextEdges.length > 1 &&
+                    !groupsOverlap(rootGroups, targetGroups)) {
+                    const from = displayPath(root);
+                    const to = displayPath(target);
+                    const intermediates = nextPath.slice(1, -1).map(displayPath);
+                    const confidence = Math.min(...nextEdges.map(graphEdgeConfidence));
+                    const bridgeEdge = {
+                        from,
+                        to,
+                        kind: "entrypoint-flow-link",
+                        direction: "directed",
+                        confidence,
+                        reason: intermediates.length > 0
+                            ? `Entrypoint flow from '${from}' reaches '${to}' via ${intermediates.join(" -> ")}.`
+                            : `Entrypoint flow from '${from}' reaches '${to}'.`,
+                    };
+                    bridgeEdges.set(`${from}\0${to}\0${bridgeEdge.kind}`, bridgeEdge);
+                }
+                if (!targetGroups &&
+                    nextEdges.length < MAX_ENTRYPOINT_FLOW_BRIDGE_HOPS &&
+                    !visited.has(target)) {
+                    visited.add(target);
+                    queue.push({
+                        node: target,
+                        path: nextPath,
+                        edges: nextEdges,
+                    });
+                }
+            }
+        }
+    }
+    return [...bridgeEdges.values()].sort(compareGraphEdges);
+}
+function buildPlanningGraphEdges(groups, graphEdges, graphBundle, lineIndex, targetPacketLines = DEFAULT_TARGET_PACKET_LINES) {
+    const bridgeEdges = buildEntrypointFlowBridgeEdges(groups, graphEdges, graphBundle);
+    const graphWithBridges = bridgeEdges.length > 0 ? [...graphEdges, ...bridgeEdges] : graphEdges;
+    const subsystemEdges = buildSubsystemClusterEdges(groups, graphWithBridges, lineIndex, targetPacketLines);
+    const graphWithSubsystems = subsystemEdges.length > 0
+        ? [...graphWithBridges, ...subsystemEdges]
+        : graphWithBridges;
+    const packageOwnershipEdges = buildPackageOwnershipClusterEdges(groups, graphWithSubsystems, lineIndex, targetPacketLines);
+    const graphWithPackageOwnership = packageOwnershipEdges.length > 0
+        ? [...graphWithSubsystems, ...packageOwnershipEdges]
+        : graphWithSubsystems;
+    const moduleOwnershipEdges = buildModuleOwnershipClusterEdges(groups, graphWithPackageOwnership, lineIndex, targetPacketLines);
+    return moduleOwnershipEdges.length > 0
+        ? [...graphWithPackageOwnership, ...moduleOwnershipEdges]
+        : graphWithPackageOwnership;
+}
+function compareGraphEdges(a, b) {
+    const confidenceDelta = graphEdgeConfidence(b) - graphEdgeConfidence(a);
+    if (confidenceDelta !== 0)
+        return confidenceDelta;
+    return (a.from.localeCompare(b.from) ||
+        a.to.localeCompare(b.to) ||
+        (a.kind ?? "").localeCompare(b.kind ?? ""));
+}
+function reviewPacketGraphEdge(edge) {
+    const result = {
+        from: edge.from,
+        to: edge.to,
+        confidence: graphEdgeConfidence(edge),
+    };
+    if (edge.kind)
+        result.kind = edge.kind;
+    if (edge.reason)
+        result.reason = edge.reason;
+    return result;
+}
+function roundQuality(value) {
+    return Math.round(value * 1000) / 1000;
+}
+function packetEntrypoints(filePaths, graphBundle) {
+    const fileSet = new Set(filePaths.map(normalizeGraphPath));
+    const routes = Array.isArray(graphBundle?.graphs.routes)
+        ? graphBundle.graphs.routes
+        : [];
+    return routes
+        .filter((route) => isRecord(route) &&
+        typeof route.handler === "string" &&
+        typeof route.path === "string" &&
+        fileSet.has(normalizeGraphPath(route.handler)))
+        .map((route) => {
+        const method = typeof route.method === "string" ? `${route.method} ` : "";
+        return `${method}${route.path} -> ${route.handler}`;
+    })
+        .sort((a, b) => a.localeCompare(b));
+}
+function buildPacketGraphContext(filePaths, graphEdges, graphBundle) {
+    const fileSet = new Set(filePaths.map(normalizeGraphPath));
+    const internalEdges = [];
+    const boundaryFiles = new Set();
+    let boundaryEdgeCount = 0;
+    for (const edge of graphEdges) {
+        if (!isConcreteGraphEdge(edge)) {
+            continue;
+        }
+        const fromInPacket = fileSet.has(normalizeGraphPath(edge.from));
+        const toInPacket = fileSet.has(normalizeGraphPath(edge.to));
+        if (fromInPacket && toInPacket) {
+            internalEdges.push(edge);
+        }
+        else if (fromInPacket !== toInPacket) {
+            boundaryEdgeCount += 1;
+            boundaryFiles.add(fromInPacket ? edge.to : edge.from);
+        }
+    }
+    const internallyConnectedFiles = new Set();
+    for (const edge of internalEdges) {
+        internallyConnectedFiles.add(normalizeGraphPath(edge.from));
+        internallyConnectedFiles.add(normalizeGraphPath(edge.to));
+    }
+    const unexplainedFileCount = filePaths.length <= 1
+        ? 0
+        : filePaths.filter((path) => !internallyConnectedFiles.has(normalizeGraphPath(path))).length;
+    const cohesionScore = filePaths.length <= 1
+        ? 1
+        : Math.min(1, internalEdges.length / (filePaths.length - 1));
+    return {
+        keyEdges: internalEdges
+            .sort(compareGraphEdges)
+            .slice(0, MAX_PACKET_KEY_EDGES)
+            .map(reviewPacketGraphEdge),
+        boundaryFiles: [...boundaryFiles]
+            .sort((a, b) => a.localeCompare(b))
+            .slice(0, MAX_PACKET_BOUNDARY_FILES),
+        entrypoints: packetEntrypoints(filePaths, graphBundle),
+        quality: {
+            cohesion_score: roundQuality(cohesionScore),
+            internal_edge_count: internalEdges.length,
+            boundary_edge_count: boundaryEdgeCount,
+            unexplained_file_count: unexplainedFileCount,
+        },
+    };
+}
 function sanitizeSegment(value) {
     const sanitized = value
         .replace(/[^a-zA-Z0-9_-]+/g, "-")
@@ -134,10 +848,11 @@ function chunkPacketTasks(tasks, options) {
     }
     return chunks;
 }
-function mergeGraphConnectedGroups(groups, graphBundle) {
+function mergeGraphConnectedGroups(groups, graphEdges) {
     const groupKeys = [...groups.keys()];
     const parent = new Map(groupKeys.map((key) => [key, key]));
-    const fileToGroupKeys = new Map();
+    const fileToGroupKeys = buildFileToGroupKeys(groups);
+    const degreeIndex = buildGraphDegreeIndex(graphEdges);
     function find(key) {
         const current = parent.get(key) ?? key;
         if (current === key)
@@ -154,14 +869,6 @@ function mergeGraphConnectedGroups(groups, graphBundle) {
         const [keep, move] = rootA.localeCompare(rootB) <= 0 ? [rootA, rootB] : [rootB, rootA];
         parent.set(move, keep);
     }
-    for (const [key, tasks] of groups) {
-        for (const path of new Set(tasks.flatMap((task) => task.file_paths))) {
-            const normalized = normalizeGraphPath(path);
-            const existing = fileToGroupKeys.get(normalized) ?? new Set();
-            existing.add(key);
-            fileToGroupKeys.set(normalized, existing);
-        }
-    }
     for (const keys of fileToGroupKeys.values()) {
         const [first, ...rest] = [...keys].sort((a, b) => a.localeCompare(b));
         if (!first)
@@ -170,8 +877,8 @@ function mergeGraphConnectedGroups(groups, graphBundle) {
             union(first, key);
         }
     }
-    for (const edge of collectGraphEdges(graphBundle)) {
-        if (!isPacketExpansionEdge(edge)) {
+    for (const edge of graphEdges) {
+        if (!isPacketExpansionEdge(edge, degreeIndex)) {
             continue;
         }
         const fromGroups = fileToGroupKeys.get(normalizeGraphPath(edge.from));
@@ -194,8 +901,9 @@ function mergeGraphConnectedGroups(groups, graphBundle) {
     }
     return [...merged.values()];
 }
-function buildPacket(tasks, packetIndex, lineIndex) {
+function buildPacket(tasks, packetIndex, lineIndex, graphEdges = [], graphBundle) {
     const filePaths = [...new Set(tasks.flatMap((task) => task.file_paths))].sort((a, b) => a.localeCompare(b));
+    const graphContext = buildPacketGraphContext(filePaths, graphEdges, graphBundle);
     const fileLineCounts = Object.fromEntries(filePaths.map((path) => {
         const owner = tasks.find((task) => task.file_paths.includes(path));
         return [path, owner ? lineCountForPath(owner, path, lineIndex) : 0];
@@ -208,6 +916,14 @@ function buildPacket(tasks, packetIndex, lineIndex) {
     const tags = [
         ...new Set(tasks.flatMap((task) => task.tags ?? [])),
     ].sort((a, b) => a.localeCompare(b));
+    const baseRationale = tasks.length === 1
+        ? tasks[0].rationale
+        : `Review ${filePaths.length} related file(s) across ${lenses.length} lens(es): ${lenses.join(", ")}.`;
+    const graphRationale = graphContext.keyEdges.length > 0
+        ? ` Key graph edges explain ${graphContext.keyEdges.length} internal relationship(s).`
+        : graphContext.boundaryFiles.length > 0
+            ? ` Boundary context is available for ${graphContext.boundaryFiles.length} adjacent file(s).`
+            : "";
     return {
         packet_id: packetIdFor(tasks, packetIndex),
         task_ids: tasks.map((task) => task.task_id),
@@ -219,25 +935,27 @@ function buildPacket(tasks, packetIndex, lineIndex) {
         total_lines: totalLines,
         priority,
         tags: tags.length > 0 ? tags : undefined,
-        rationale: tasks.length === 1
-            ? tasks[0].rationale
-            : `Review ${filePaths.length} related file(s) across ${lenses.length} lens(es): ${lenses.join(", ")}.`,
+        entrypoints: graphContext.entrypoints.length > 0
+            ? graphContext.entrypoints
+            : undefined,
+        key_edges: graphContext.keyEdges.length > 0 ? graphContext.keyEdges : undefined,
+        boundary_files: graphContext.boundaryFiles.length > 0
+            ? graphContext.boundaryFiles
+            : undefined,
+        quality: graphContext.quality,
+        rationale: `${baseRationale}${graphRationale}`,
         estimated_tokens: ESTIMATED_PACKET_PROMPT_TOKENS + totalLines * ESTIMATED_TOKENS_PER_LINE,
     };
 }
-export function buildReviewPackets(tasks, options = {}) {
+function buildReviewPacketPlanningData(tasks, options = {}) {
     const maxTasksPerPacket = options.maxTasksPerPacket ?? DEFAULT_MAX_TASKS_PER_PACKET;
     const targetPacketLines = options.targetPacketLines ?? DEFAULT_TARGET_PACKET_LINES;
-    const groups = new Map();
-    for (const task of tasks) {
-        const key = packetGroupingKey(task);
-        const group = groups.get(key) ?? [];
-        group.push(task);
-        groups.set(key, group);
-    }
+    const graphEdges = collectGraphEdges(options.graphBundle);
+    const groups = buildTaskGroups(tasks);
+    const planningGraphEdges = buildPlanningGraphEdges(groups, graphEdges, options.graphBundle, options.lineIndex, targetPacketLines);
     const packets = [];
     let packetIndex = 0;
-    const groupedTasks = mergeGraphConnectedGroups(groups, options.graphBundle).sort((a, b) => {
+    const groupedTasks = mergeGraphConnectedGroups(groups, planningGraphEdges).sort((a, b) => {
         const aPriority = Math.max(...a.map((task) => priorityRank(task.priority)));
         const bPriority = Math.max(...b.map((task) => priorityRank(task.priority)));
         if (aPriority !== bPriority)
@@ -250,11 +968,19 @@ export function buildReviewPackets(tasks, options = {}) {
             maxTasksPerPacket,
             targetPacketLines,
         })) {
-            packets.push(buildPacket(chunk, packetIndex, options.lineIndex));
+            packets.push(buildPacket(chunk, packetIndex, options.lineIndex, planningGraphEdges, options.graphBundle));
             packetIndex += 1;
         }
     }
-    return packets.sort(comparePackets);
+    return {
+        graphEdges,
+        groups,
+        planningGraphEdges,
+        packets: packets.sort(comparePackets),
+    };
+}
+export function buildReviewPackets(tasks, options = {}) {
+    return buildReviewPacketPlanningData(tasks, options).packets;
 }
 export function orderTasksForPacketReview(tasks, options = {}) {
     const taskById = new Map(tasks.map((task) => [task.task_id, task]));
@@ -262,8 +988,253 @@ export function orderTasksForPacketReview(tasks, options = {}) {
         .map((taskId) => taskById.get(taskId))
         .filter((task) => task !== undefined));
 }
+function countHighDegreeTaskFiles(degreeMap, taskFiles) {
+    let count = 0;
+    for (const [path, degree] of degreeMap) {
+        if (degree > HIGH_FAN_DEGREE_THRESHOLD && taskFiles.has(path)) {
+            count += 1;
+        }
+    }
+    return count;
+}
+function edgeKindKey(edge) {
+    const kind = edge.kind?.trim();
+    return kind && kind.length > 0 ? kind : "unknown";
+}
+function edgeIdentity(edge) {
+    return [
+        normalizeGraphPath(edge.from),
+        normalizeGraphPath(edge.to),
+        edgeKindKey(edge),
+    ].join("\0");
+}
+function incrementEdgeKindCount(counts, edge) {
+    const key = edgeKindKey(edge);
+    counts[key] = (counts[key] ?? 0) + 1;
+}
+function sortCountRecord(counts) {
+    return Object.fromEntries(Object.entries(counts).sort((a, b) => a[0].localeCompare(b[0])));
+}
+function buildTaskToGroupKey(groups) {
+    const taskToGroupKey = new Map();
+    for (const [groupKey, tasks] of groups) {
+        for (const task of tasks) {
+            taskToGroupKey.set(task.task_id, groupKey);
+        }
+    }
+    return taskToGroupKey;
+}
+function buildGroupToPacketIds(packets, groups) {
+    const taskToGroupKey = buildTaskToGroupKey(groups);
+    const groupToPacketIds = new Map();
+    for (const packet of packets) {
+        const packetGroupKeys = new Set(packet.task_ids
+            .map((taskId) => taskToGroupKey.get(taskId))
+            .filter((groupKey) => groupKey !== undefined));
+        for (const groupKey of packetGroupKeys) {
+            const packetIds = groupToPacketIds.get(groupKey) ?? new Set();
+            packetIds.add(packet.packet_id);
+            groupToPacketIds.set(groupKey, packetIds);
+        }
+    }
+    return groupToPacketIds;
+}
+function setsOverlap(a, b) {
+    if (!a || !b) {
+        return false;
+    }
+    for (const value of a) {
+        if (b.has(value)) {
+            return true;
+        }
+    }
+    return false;
+}
+function countMergeEdgeKinds(packets, groups, planningGraphEdges) {
+    const counts = {};
+    const seen = new Set();
+    const fileToGroupKeys = buildFileToGroupKeys(groups);
+    const groupToPacketIds = buildGroupToPacketIds(packets, groups);
+    const degreeIndex = buildGraphDegreeIndex(planningGraphEdges);
+    for (const edge of planningGraphEdges) {
+        if (!isPacketExpansionEdge(edge, degreeIndex)) {
+            continue;
+        }
+        const fromGroups = fileToGroupKeys.get(normalizeGraphPath(edge.from));
+        const toGroups = fileToGroupKeys.get(normalizeGraphPath(edge.to));
+        if (!fromGroups || !toGroups) {
+            continue;
+        }
+        let mergedDistinctGroups = false;
+        for (const fromKey of fromGroups) {
+            for (const toKey of toGroups) {
+                if (fromKey !== toKey &&
+                    setsOverlap(groupToPacketIds.get(fromKey), groupToPacketIds.get(toKey))) {
+                    mergedDistinctGroups = true;
+                    break;
+                }
+            }
+            if (mergedDistinctGroups) {
+                break;
+            }
+        }
+        const identity = edgeIdentity(edge);
+        if (mergedDistinctGroups && !seen.has(identity)) {
+            seen.add(identity);
+            incrementEdgeKindCount(counts, edge);
+        }
+    }
+    return sortCountRecord(counts);
+}
+function buildFileToPacketIds(packets) {
+    const fileToPacketIds = new Map();
+    for (const packet of packets) {
+        for (const path of packet.file_paths) {
+            const normalized = normalizeGraphPath(path);
+            const packetIds = fileToPacketIds.get(normalized) ?? new Set();
+            packetIds.add(packet.packet_id);
+            fileToPacketIds.set(normalized, packetIds);
+        }
+    }
+    return fileToPacketIds;
+}
+function countBoundaryOnlyEdgeKinds(packets, planningGraphEdges) {
+    const counts = {};
+    const seen = new Set();
+    const fileToPacketIds = buildFileToPacketIds(packets);
+    for (const edge of planningGraphEdges) {
+        if (!isConcreteGraphEdge(edge)) {
+            continue;
+        }
+        const fromPacketIds = fileToPacketIds.get(normalizeGraphPath(edge.from));
+        const toPacketIds = fileToPacketIds.get(normalizeGraphPath(edge.to));
+        if (!fromPacketIds && !toPacketIds) {
+            continue;
+        }
+        if (setsOverlap(fromPacketIds, toPacketIds)) {
+            continue;
+        }
+        const identity = edgeIdentity(edge);
+        if (!seen.has(identity)) {
+            seen.add(identity);
+            incrementEdgeKindCount(counts, edge);
+        }
+    }
+    return sortCountRecord(counts);
+}
+function isWeaklyExplainedPacket(packet) {
+    return (packet.file_paths.length > 1 &&
+        (packet.quality.internal_edge_count === 0 ||
+            packet.quality.cohesion_score < 1 ||
+            packet.quality.unexplained_file_count > 0));
+}
+function weaklyExplainedPackets(packets) {
+    return packets.filter(isWeaklyExplainedPacket);
+}
+function weaklyExplainedPacketIds(weakPackets) {
+    return weakPackets
+        .map((packet) => packet.packet_id)
+        .sort((a, b) => a.localeCompare(b));
+}
+function weakPacketPrimaryGap(packet) {
+    if (packet.quality.internal_edge_count === 0) {
+        return "missing_internal_edges";
+    }
+    if (packet.quality.unexplained_file_count > 0) {
+        return "unexplained_files";
+    }
+    return "partial_cohesion";
+}
+function weaklyExplainedGapCounts(weakPackets) {
+    const counts = {
+        missing_internal_edges: 0,
+        unexplained_files: 0,
+        partial_cohesion: 0,
+    };
+    for (const packet of weakPackets) {
+        counts[weakPacketPrimaryGap(packet)] += 1;
+    }
+    return Object.fromEntries(WEAK_PACKET_GAP_ORDER.map((gap) => [gap, counts[gap]]));
+}
+function fileExtensionBucket(path) {
+    const basename = normalizeGraphPath(path).split("/").at(-1) ?? "";
+    const extensionStart = basename.lastIndexOf(".");
+    if (extensionStart <= 0 || extensionStart === basename.length - 1) {
+        return "no_extension";
+    }
+    return basename.slice(extensionStart).toLowerCase();
+}
+function weaklyExplainedFileExtensionCounts(weakPackets) {
+    const counts = {};
+    const seenPaths = new Set();
+    for (const packet of weakPackets) {
+        for (const path of packet.file_paths) {
+            const normalized = normalizeGraphPath(path);
+            if (seenPaths.has(normalized)) {
+                continue;
+            }
+            seenPaths.add(normalized);
+            const extension = fileExtensionBucket(path);
+            counts[extension] = (counts[extension] ?? 0) + 1;
+        }
+    }
+    return sortCountRecord(counts);
+}
+function weaklyExplainedPacketSamples(weakPackets) {
+    return weakPackets
+        .sort((a, b) => b.quality.unexplained_file_count - a.quality.unexplained_file_count ||
+        a.quality.cohesion_score - b.quality.cohesion_score ||
+        b.file_paths.length - a.file_paths.length ||
+        a.packet_id.localeCompare(b.packet_id))
+        .slice(0, MAX_WEAK_PACKET_SAMPLES)
+        .map((packet) => ({
+        packet_id: packet.packet_id,
+        primary_gap: weakPacketPrimaryGap(packet),
+        file_count: packet.file_paths.length,
+        sample_file_paths: packet.file_paths.slice(0, MAX_WEAK_PACKET_SAMPLE_FILES),
+        cohesion_score: packet.quality.cohesion_score,
+        internal_edge_count: packet.quality.internal_edge_count,
+        boundary_edge_count: packet.quality.boundary_edge_count,
+        unexplained_file_count: packet.quality.unexplained_file_count,
+    }));
+}
+function buildPacketQualityMetrics(packets, tasks, graphEdges, planningGraphEdges, groups) {
+    const packetTaskIds = new Set(packets.flatMap((packet) => packet.task_ids));
+    const orphanTaskCount = tasks.filter((task) => !packetTaskIds.has(task.task_id)).length;
+    const degreeIndex = buildGraphDegreeIndex(graphEdges);
+    const taskFiles = new Set(tasks.flatMap((task) => task.file_paths.map(normalizeGraphPath)));
+    const largestUnexplainedPacket = packets.reduce((largest, packet) => !largest ||
+        packet.quality.unexplained_file_count >
+            largest.quality.unexplained_file_count
+        ? packet
+        : largest, undefined);
+    const largestUnexplainedFiles = largestUnexplainedPacket?.quality.unexplained_file_count ?? 0;
+    const weakPackets = weaklyExplainedPackets(packets);
+    const weakPacketIds = weaklyExplainedPacketIds(weakPackets);
+    const weakPacketSamples = weaklyExplainedPacketSamples(weakPackets);
+    return {
+        average_cohesion_score: packets.length > 0
+            ? roundQuality(packets.reduce((sum, packet) => sum + packet.quality.cohesion_score, 0) / packets.length)
+            : 0,
+        boundary_crossing_count: packets.reduce((sum, packet) => sum + packet.quality.boundary_edge_count, 0),
+        merge_edge_kind_counts: countMergeEdgeKinds(packets, groups, planningGraphEdges),
+        boundary_edge_kind_counts: countBoundaryOnlyEdgeKinds(packets, planningGraphEdges),
+        orphan_task_count: orphanTaskCount,
+        high_fan_in_file_count: countHighDegreeTaskFiles(degreeIndex.fanIn, taskFiles),
+        high_fan_out_file_count: countHighDegreeTaskFiles(degreeIndex.fanOut, taskFiles),
+        weakly_explained_gap_counts: weaklyExplainedGapCounts(weakPackets),
+        weakly_explained_file_extension_counts: weaklyExplainedFileExtensionCounts(weakPackets),
+        weakly_explained_packet_count: weakPacketIds.length,
+        weakly_explained_packet_ids: weakPacketIds,
+        weakly_explained_packet_samples: weakPacketSamples,
+        largest_unexplained_packet_id: largestUnexplainedFiles > 0
+            ? largestUnexplainedPacket?.packet_id
+            : undefined,
+        largest_unexplained_packet_files: largestUnexplainedFiles,
+    };
+}
 export function buildAuditPlanMetrics(tasks, options = {}) {
-    const packets = buildReviewPackets(tasks, options);
+    const { graphEdges, groups, packets, planningGraphEdges } = buildReviewPacketPlanningData(tasks, options);
     const taskLineCounts = tasks.map((task) => taskLineCount(task, options.lineIndex));
     const totalTaskLines = taskLineCounts.reduce((sum, value) => sum + value, 0);
     const totalPacketLines = packets.reduce((sum, packet) => sum + packet.total_lines, 0);
@@ -300,6 +1271,7 @@ export function buildAuditPlanMetrics(tasks, options = {}) {
         largest_packet_id: largestPacket?.packet_id,
         lens_task_counts: lensTaskCounts,
         priority_task_counts: priorityTaskCounts,
+        packet_quality: buildPacketQualityMetrics(packets, tasks, graphEdges, planningGraphEdges, groups),
         packet_size: {
             single_task_packets: packets.filter((packet) => packet.task_ids.length === 1).length,
             multi_task_packets: packets.filter((packet) => packet.task_ids.length > 1).length,