auditor-lambda 0.3.2 → 0.3.4

package/dist/orchestrator/dependencyMap.js

@@ -12,6 +12,8 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "coverage_matrix.json",
         "flow_coverage.json",
         "audit_tasks.json",
+        "audit_plan_metrics.json",
+        "review_packets.json",
         "requeue_tasks.json",
         "runtime_validation_tasks.json",
         "runtime_validation_report.json",
@@ -26,6 +28,8 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "coverage_matrix.json",
         "flow_coverage.json",
         "audit_tasks.json",
+        "audit_plan_metrics.json",
+        "review_packets.json",
         "requeue_tasks.json",
         "runtime_validation_tasks.json",
         "runtime_validation_report.json",
@@ -35,6 +39,8 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "risk_register.json",
         "coverage_matrix.json",
         "audit_tasks.json",
+        "audit_plan_metrics.json",
+        "review_packets.json",
         "runtime_validation_tasks.json",
         "requeue_tasks.json",
         "audit-report.md",
@@ -49,6 +55,8 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "flow_coverage.json",
         "risk_register.json",
         "audit_tasks.json",
+        "audit_plan_metrics.json",
+        "review_packets.json",
         "requeue_tasks.json",
         "runtime_validation_tasks.json",
         "runtime_validation_report.json",
@@ -58,12 +66,16 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "coverage_matrix.json",
         "flow_coverage.json",
         "requeue_tasks.json",
+        "audit_plan_metrics.json",
+        "review_packets.json",
         "runtime_validation_tasks.json",
         "runtime_validation_report.json",
         "audit-report.md",
     ],
     "coverage_matrix.json": [
         "flow_coverage.json",
+        "audit_plan_metrics.json",
+        "review_packets.json",
         "requeue_tasks.json",
         "runtime_validation_tasks.json",
         "runtime_validation_report.json",
@@ -75,6 +87,12 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "runtime_validation_report.json",
         "audit-report.md",
     ],
+    "audit_tasks.json": [
+        "audit_plan_metrics.json",
+        "review_packets.json",
+    ],
+    "audit_plan_metrics.json": [],
+    "review_packets.json": [],
     "runtime_validation_report.json": [
         "audit-report.md",
     ],

package/dist/orchestrator/internalExecutors.d.ts

@@ -8,7 +8,7 @@ export interface ExecutorRunResult {
     progress_summary: string;
 }
 export declare function runIntakeExecutor(bundle: ArtifactBundle, root: string): Promise<ExecutorRunResult>;
-export declare function runStructureExecutor(bundle: ArtifactBundle): ExecutorRunResult;
+export declare function runStructureExecutor(bundle: ArtifactBundle, root?: string): Promise<ExecutorRunResult>;
 export declare function runPlanningExecutor(bundle: ArtifactBundle, root: string, lineIndex?: Record<string, number>): Promise<ExecutorRunResult>;
 export declare function runResultIngestionExecutor(bundle: ArtifactBundle, results: AuditResult[]): ExecutorRunResult;
 export declare function runRuntimeValidationExecutor(bundle: ArtifactBundle, root: string): Promise<ExecutorRunResult>;

package/dist/orchestrator/internalExecutors.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { buildFileDisposition } from "../extractors/disposition.js";
-import { buildGraphBundle } from "../extractors/graph.js";
+import { buildGraphBundle, buildGraphBundleFromFs, } from "../extractors/graph.js";
 import { buildCriticalFlowManifest } from "../extractors/flows.js";
 import { buildRiskRegister } from "../extractors/risk.js";
 import { buildSurfaceManifest } from "../extractors/surfaces.js";
@@ -10,12 +10,50 @@ import { buildRequeuePayload } from "./requeueCommand.js";
 import { buildRuntimeValidationTasks, discoverRuntimeValidationCommand, mergeRuntimeValidationReport, } from "./runtimeValidation.js";
 import { buildAuditReportModel, renderAuditReportMarkdown, } from "../reporting/synthesis.js";
 import { buildChunkedAuditTasks, } from "./taskBuilder.js";
+import { buildAuditPlanMetrics, buildReviewPackets, } from "./reviewPackets.js";
 import { buildUnitManifest } from "./unitBuilder.js";
 import { buildRepoManifestFromFs } from "../extractors/fsIntake.js";
 import { loadIgnoreFile } from "../extractors/ignore.js";
 import { ingestAuditResults, updateAuditTaskStatuses, } from "./resultIngestion.js";
+import { buildSelectiveDeepeningTasks } from "./selectiveDeepening.js";
 import { updateRuntimeValidationReport } from "./runtimeValidationUpdate.js";
 import { autoCompleteTrivialCoverage } from "./trivialAudit.js";
+function lineIndexFromTasks(tasks) {
+    return Object.fromEntries((tasks ?? []).flatMap((task) => Object.entries(task.file_line_counts ?? {})));
+}
+function appendSelectiveDeepeningTasks(params) {
+    if (!params.bundle.audit_tasks) {
+        return { bundle: params.bundle, taskCount: 0, artifacts: [] };
+    }
+    const lineIndex = lineIndexFromTasks(params.bundle.audit_tasks);
+    const selectiveDeepeningTasks = buildSelectiveDeepeningTasks({
+        existingTasks: params.bundle.audit_tasks,
+        results: params.results,
+        lineIndex,
+        runtimeValidationTasks: params.bundle.runtime_validation_tasks,
+        runtimeValidationReport: params.runtimeValidationReport ?? params.bundle.runtime_validation_report,
+    });
+    if (selectiveDeepeningTasks.length === 0) {
+        return { bundle: params.bundle, taskCount: 0, artifacts: [] };
+    }
+    const auditTasks = [...params.bundle.audit_tasks, ...selectiveDeepeningTasks];
+    return {
+        bundle: {
+            ...params.bundle,
+            audit_tasks: auditTasks,
+            audit_plan_metrics: buildAuditPlanMetrics(auditTasks, {
+                graphBundle: params.bundle.graph_bundle,
+                lineIndex,
+            }),
+            review_packets: buildReviewPackets(auditTasks, {
+                graphBundle: params.bundle.graph_bundle,
+                lineIndex,
+            }),
+        },
+        taskCount: selectiveDeepeningTasks.length,
+        artifacts: ["audit_tasks.json", "audit_plan_metrics.json", "review_packets.json"],
+    };
+}
 async function runCommand(command, cwd) {
     return await new Promise((resolve) => {
         const child = spawn(command[0], command.slice(1), {
@@ -69,7 +107,7 @@ export async function runIntakeExecutor(bundle, root) {
         progress_summary: `Created intake artifacts for ${repoManifest.files.length} files.`,
     };
 }
-export function runStructureExecutor(bundle) {
+export async function runStructureExecutor(bundle, root) {
     if (!bundle.repo_manifest) {
         throw new Error("Cannot run structure executor without repo_manifest");
     }
@@ -77,7 +115,9 @@ export function runStructureExecutor(bundle) {
     const disposition = bundle.file_disposition ?? buildFileDisposition(bundle.repo_manifest);
     const unitManifest = buildUnitManifest(bundle.repo_manifest, disposition);
     const surfaceManifest = buildSurfaceManifest(bundle.repo_manifest, disposition);
-    const graphBundle = buildGraphBundle(bundle.repo_manifest, disposition);
+    const graphBundle = root
+        ? await buildGraphBundleFromFs(bundle.repo_manifest, root, disposition)
+        : buildGraphBundle(bundle.repo_manifest, disposition);
     const criticalFlows = buildCriticalFlowManifest(bundle.repo_manifest, surfaceManifest, disposition);
     const riskRegister = buildRiskRegister(unitManifest, criticalFlows, externalAnalyzerResults);
     return {
@@ -137,6 +177,14 @@ export async function runPlanningExecutor(bundle, root, lineIndex = {}) {
         ...task,
         status: task.status ?? "pending",
     }));
+    const reviewPackets = buildReviewPackets(taggedAuditTasks, {
+        graphBundle: bundle.graph_bundle,
+        lineIndex,
+    });
+    const auditPlanMetrics = buildAuditPlanMetrics(taggedAuditTasks, {
+        graphBundle: bundle.graph_bundle,
+        lineIndex,
+    });
     const requeuePayload = buildRequeuePayload(coverage, bundle.critical_flows, flowCoverage, externalAnalyzerResults);
     return {
         updated: {
@@ -146,6 +194,8 @@ export async function runPlanningExecutor(bundle, root, lineIndex = {}) {
             runtime_validation_tasks: runtimeValidationTasks,
             runtime_validation_report: runtimeValidationReport,
             audit_tasks: taggedAuditTasks,
+            audit_plan_metrics: auditPlanMetrics,
+            review_packets: reviewPackets,
             requeue_tasks: requeuePayload.tasks,
             audit_report: undefined,
         },
@@ -155,9 +205,11 @@ export async function runPlanningExecutor(bundle, root, lineIndex = {}) {
             "runtime_validation_tasks.json",
             ...(runtimeValidationReport ? ["runtime_validation_report.json"] : []),
             "audit_tasks.json",
+            "audit_plan_metrics.json",
+            "review_packets.json",
             "requeue_tasks.json",
         ],
-        progress_summary: `Built planning artifacts; generated ${taggedAuditTasks.length} review blocks and ${requeuePayload.task_count} requeue tasks.` +
+        progress_summary: `Built planning artifacts; generated ${taggedAuditTasks.length} review tasks in ${reviewPackets.length} packet(s) and ${requeuePayload.task_count} requeue tasks.` +
             (skippedTrivialPaths.length > 0
                 ? ` Skipped ${skippedTrivialPaths.length} trivial path${skippedTrivialPaths.length === 1 ? "" : "s"} from semantic review.`
                 : "") +
@@ -188,19 +240,25 @@ export function runResultIngestionExecutor(bundle, results) {
         : bundle.runtime_validation_report;
     const requeuePayload = buildRequeuePayload(updatedCoverageMatrix, bundle.critical_flows, flowCoverage, bundle.external_analyzer_results);
     const mergedResults = [...(bundle.audit_results ?? []), ...results];
-    const updatedAuditTasks = updateAuditTaskStatuses(bundle.audit_tasks, mergedResults);
+    const completedAuditTasks = updateAuditTaskStatuses(bundle.audit_tasks, mergedResults);
+    const baseUpdatedBundle = {
+        ...bundle,
+        coverage_matrix: updatedCoverageMatrix,
+        flow_coverage: flowCoverage,
+        runtime_validation_tasks: runtimeValidationTasks,
+        runtime_validation_report: runtimeValidationReport,
+        audit_results: mergedResults,
+        audit_tasks: completedAuditTasks,
+        requeue_tasks: requeuePayload.tasks,
+        audit_report: undefined,
+    };
+    const selectiveDeepening = appendSelectiveDeepeningTasks({
+        bundle: baseUpdatedBundle,
+        results: mergedResults,
+        runtimeValidationReport,
+    });
     return {
-        updated: {
-            ...bundle,
-            coverage_matrix: updatedCoverageMatrix,
-            flow_coverage: flowCoverage,
-            runtime_validation_tasks: runtimeValidationTasks,
-            runtime_validation_report: runtimeValidationReport,
-            audit_results: mergedResults,
-            audit_tasks: updatedAuditTasks,
-            requeue_tasks: requeuePayload.tasks,
-            audit_report: undefined,
-        },
+        updated: selectiveDeepening.bundle,
         artifacts_written: [
             "coverage_matrix.json",
             "flow_coverage.json",
@@ -208,9 +266,13 @@ export function runResultIngestionExecutor(bundle, results) {
             ...(runtimeValidationReport ? ["runtime_validation_report.json"] : []),
             "audit_results.jsonl",
             "audit_tasks.json",
+            ...selectiveDeepening.artifacts.filter((artifact) => artifact !== "audit_tasks.json"),
             "requeue_tasks.json",
         ],
-        progress_summary: `Ingested ${results.length} audit result entries and refreshed dependent artifacts.`,
+        progress_summary: `Ingested ${results.length} audit result entries and refreshed dependent artifacts.` +
+            (selectiveDeepening.taskCount > 0
+                ? ` Added ${selectiveDeepening.taskCount} selective deepening task(s).`
+                : ""),
     };
 }
 export async function runRuntimeValidationExecutor(bundle, root) {
@@ -247,16 +309,29 @@ export async function runRuntimeValidationExecutor(bundle, root) {
             notes: [`Target paths: ${task.target_paths.join(", ")}`],
         });
     }
+    const runtimeValidationReport = {
+        results: [...byTaskId.values()].sort((a, b) => a.task_id.localeCompare(b.task_id)),
+    };
+    const baseUpdatedBundle = {
+        ...bundle,
+        runtime_validation_report: runtimeValidationReport,
+        audit_report: undefined,
+    };
+    const selectiveDeepening = appendSelectiveDeepeningTasks({
+        bundle: baseUpdatedBundle,
+        results: bundle.audit_results ?? [],
+        runtimeValidationReport,
+    });
     return {
-        updated: {
-            ...bundle,
-            runtime_validation_report: {
-                results: [...byTaskId.values()].sort((a, b) => a.task_id.localeCompare(b.task_id)),
-            },
-            audit_report: undefined,
-        },
-        artifacts_written: ["runtime_validation_report.json"],
-        progress_summary: `Executed deterministic runtime validation for ${bundle.runtime_validation_tasks.tasks.length} task(s).`,
+        updated: selectiveDeepening.bundle,
+        artifacts_written: [
+            "runtime_validation_report.json",
+            ...selectiveDeepening.artifacts,
+        ],
+        progress_summary: `Executed deterministic runtime validation for ${bundle.runtime_validation_tasks.tasks.length} task(s).` +
+            (selectiveDeepening.taskCount > 0
+                ? ` Added ${selectiveDeepening.taskCount} selective deepening task(s).`
+                : ""),
     };
 }
 export function runRuntimeValidationUpdateExecutor(bundle, updates) {
@@ -265,14 +340,26 @@ export function runRuntimeValidationUpdateExecutor(bundle, updates) {
     }
     const existingReport = bundle.runtime_validation_report ?? { results: [] };
     const mergedReport = updateRuntimeValidationReport(bundle.runtime_validation_tasks, existingReport, updates);
+    const baseUpdatedBundle = {
+        ...bundle,
+        runtime_validation_report: mergedReport,
+        audit_report: undefined,
+    };
+    const selectiveDeepening = appendSelectiveDeepeningTasks({
+        bundle: baseUpdatedBundle,
+        results: bundle.audit_results ?? [],
+        runtimeValidationReport: mergedReport,
+    });
     return {
-        updated: {
-            ...bundle,
-            runtime_validation_report: mergedReport,
-            audit_report: undefined,
-        },
-        artifacts_written: ["runtime_validation_report.json"],
-        progress_summary: `Merged ${updates.results.length} runtime validation updates.`,
+        updated: selectiveDeepening.bundle,
+        artifacts_written: [
+            "runtime_validation_report.json",
+            ...selectiveDeepening.artifacts,
+        ],
+        progress_summary: `Merged ${updates.results.length} runtime validation updates.` +
+            (selectiveDeepening.taskCount > 0
+                ? ` Added ${selectiveDeepening.taskCount} selective deepening task(s).`
+                : ""),
     };
 }
 export function runSynthesisExecutor(bundle, results) {

package/dist/orchestrator/reviewPackets.d.ts

@@ -0,0 +1,14 @@
+import type { AuditTask } from "../types.js";
+import type { AuditPlanMetrics, ReviewPacket } from "../types/reviewPlanning.js";
+import type { GraphBundle } from "../types/graph.js";
+export interface BuildReviewPacketOptions {
+    graphBundle?: GraphBundle;
+    lineIndex?: Record<string, number>;
+    maxTasksPerPacket?: number;
+    targetPacketLines?: number;
+}
+export declare function buildReviewPackets(tasks: AuditTask[], options?: BuildReviewPacketOptions): ReviewPacket[];
+export declare function orderTasksForPacketReview(tasks: AuditTask[], options?: BuildReviewPacketOptions): AuditTask[];
+export declare function buildAuditPlanMetrics(tasks: AuditTask[], options?: BuildReviewPacketOptions & {
+    generatedAt?: Date;
+}): AuditPlanMetrics;

package/dist/orchestrator/reviewPackets.js

@@ -0,0 +1,300 @@
+import { createHash } from "node:crypto";
+import { LENS_ORDER } from "./unitBuilder.js";
+const DEFAULT_MAX_TASKS_PER_PACKET = 6;
+const DEFAULT_TARGET_PACKET_LINES = 2500;
+const ESTIMATED_TOKENS_PER_LINE = 4;
+const ESTIMATED_PACKET_PROMPT_TOKENS = 900;
+function priorityRank(priority) {
+    switch (priority) {
+        case "high":
+            return 3;
+        case "medium":
+            return 2;
+        case "low":
+        default:
+            return 1;
+    }
+}
+function normalizePriority(priority) {
+    return priority ?? "low";
+}
+function sortLenses(lenses) {
+    const set = new Set(lenses);
+    return LENS_ORDER.filter((lens) => set.has(lens));
+}
+function lineCountForPath(task, path, lineIndex) {
+    return task.file_line_counts?.[path] ?? lineIndex?.[path] ?? 0;
+}
+function taskLineCount(task, lineIndex) {
+    return task.file_paths.reduce((sum, path) => sum + lineCountForPath(task, path, lineIndex), 0);
+}
+function taskFileSignature(task) {
+    return [...new Set(task.file_paths)].sort((a, b) => a.localeCompare(b)).join("\0");
+}
+function packetGroupingKey(task) {
+    const criticalFlowTag = task.tags?.find((tag) => tag.startsWith("critical_flow:"));
+    const scope = criticalFlowTag ?? task.unit_id;
+    return `${scope}\0${taskFileSignature(task)}`;
+}
+function normalizeGraphPath(path) {
+    return path.replace(/\\/g, "/").replace(/^\.\//, "").toLowerCase();
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function collectGraphEdges(graphBundle) {
+    if (!graphBundle?.graphs) {
+        return [];
+    }
+    const edges = [];
+    for (const key of ["imports", "calls", "references"]) {
+        const raw = graphBundle.graphs[key];
+        if (!Array.isArray(raw)) {
+            continue;
+        }
+        for (const item of raw) {
+            if (!isRecord(item)) {
+                continue;
+            }
+            if (typeof item.from !== "string" || typeof item.to !== "string") {
+                continue;
+            }
+            edges.push({
+                from: item.from,
+                to: item.to,
+                kind: typeof item.kind === "string" ? item.kind : undefined,
+            });
+        }
+    }
+    return edges;
+}
+function isPacketExpansionEdge(edge) {
+    return edge.kind !== "heuristic-container-edge";
+}
+function sanitizeSegment(value) {
+    const sanitized = value
+        .replace(/[^a-zA-Z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return sanitized.length > 0 ? sanitized : "packet";
+}
+function packetIdFor(tasks, packetIndex) {
+    const unit = sanitizeSegment(tasks[0]?.unit_id ?? "review");
+    const lenses = sortLenses(tasks.map((task) => task.lens)).join("-");
+    const hash = createHash("sha1")
+        .update(tasks.map((task) => task.task_id).join("\0"))
+        .digest("hex")
+        .slice(0, 10);
+    return `${unit}:${lenses}:packet-${packetIndex + 1}-${hash}`;
+}
+function compareTasksForPacket(a, b) {
+    const lensDelta = LENS_ORDER.indexOf(a.lens) - LENS_ORDER.indexOf(b.lens);
+    if (lensDelta !== 0)
+        return lensDelta;
+    return a.task_id.localeCompare(b.task_id);
+}
+function comparePackets(a, b) {
+    const priorityDelta = priorityRank(b.priority) - priorityRank(a.priority);
+    if (priorityDelta !== 0)
+        return priorityDelta;
+    const sizeDelta = b.task_ids.length - a.task_ids.length;
+    if (sizeDelta !== 0)
+        return sizeDelta;
+    return a.packet_id.localeCompare(b.packet_id);
+}
+function chunkPacketTasks(tasks, options) {
+    const chunks = [];
+    let current = [];
+    for (const task of tasks.sort(compareTasksForPacket)) {
+        const candidate = [...current, task];
+        const uniquePaths = new Set(candidate.flatMap((item) => item.file_paths));
+        const candidateLines = [...uniquePaths].reduce((sum, path) => {
+            const owner = candidate.find((item) => item.file_paths.includes(path));
+            return sum + (owner ? lineCountForPath(owner, path, options.lineIndex) : 0);
+        }, 0);
+        const wouldExceedTaskCount = current.length > 0 && candidate.length > options.maxTasksPerPacket;
+        const wouldExceedLines = current.length > 0 && candidateLines > options.targetPacketLines;
+        if (wouldExceedTaskCount || wouldExceedLines) {
+            chunks.push(current);
+            current = [];
+        }
+        current.push(task);
+    }
+    if (current.length > 0) {
+        chunks.push(current);
+    }
+    return chunks;
+}
+function mergeGraphConnectedGroups(groups, graphBundle) {
+    const groupKeys = [...groups.keys()];
+    const parent = new Map(groupKeys.map((key) => [key, key]));
+    const fileToGroupKeys = new Map();
+    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 [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)
+            continue;
+        for (const key of rest) {
+            union(first, key);
+        }
+    }
+    for (const edge of collectGraphEdges(graphBundle)) {
+        if (!isPacketExpansionEdge(edge)) {
+            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);
+            }
+        }
+    }
+    const merged = new Map();
+    for (const key of groupKeys) {
+        const root = find(key);
+        const current = merged.get(root) ?? [];
+        current.push(...(groups.get(key) ?? []));
+        merged.set(root, current);
+    }
+    return [...merged.values()];
+}
+function buildPacket(tasks, packetIndex, lineIndex) {
+    const filePaths = [...new Set(tasks.flatMap((task) => task.file_paths))].sort((a, b) => a.localeCompare(b));
+    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];
+    }));
+    const totalLines = Object.values(fileLineCounts).reduce((sum, value) => sum + value, 0);
+    const priority = tasks.reduce((highest, task) => priorityRank(task.priority) > priorityRank(highest)
+        ? normalizePriority(task.priority)
+        : highest, "low");
+    const lenses = sortLenses(tasks.map((task) => task.lens));
+    const tags = [
+        ...new Set(tasks.flatMap((task) => task.tags ?? [])),
+    ].sort((a, b) => a.localeCompare(b));
+    return {
+        packet_id: packetIdFor(tasks, packetIndex),
+        task_ids: tasks.map((task) => task.task_id),
+        unit_ids: [...new Set(tasks.map((task) => task.unit_id))].sort((a, b) => a.localeCompare(b)),
+        pass_ids: [...new Set(tasks.map((task) => task.pass_id))].sort((a, b) => a.localeCompare(b)),
+        lenses,
+        file_paths: filePaths,
+        file_line_counts: fileLineCounts,
+        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(", ")}.`,
+        estimated_tokens: ESTIMATED_PACKET_PROMPT_TOKENS + totalLines * ESTIMATED_TOKENS_PER_LINE,
+    };
+}
+export function buildReviewPackets(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 packets = [];
+    let packetIndex = 0;
+    const groupedTasks = mergeGraphConnectedGroups(groups, options.graphBundle).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)
+            return bPriority - aPriority;
+        return (a[0]?.task_id ?? "").localeCompare(b[0]?.task_id ?? "");
+    });
+    for (const group of groupedTasks) {
+        for (const chunk of chunkPacketTasks(group, {
+            lineIndex: options.lineIndex,
+            maxTasksPerPacket,
+            targetPacketLines,
+        })) {
+            packets.push(buildPacket(chunk, packetIndex, options.lineIndex));
+            packetIndex += 1;
+        }
+    }
+    return packets.sort(comparePackets);
+}
+export function orderTasksForPacketReview(tasks, options = {}) {
+    const taskById = new Map(tasks.map((task) => [task.task_id, task]));
+    return buildReviewPackets(tasks, options).flatMap((packet) => packet.task_ids
+        .map((taskId) => taskById.get(taskId))
+        .filter((task) => task !== undefined));
+}
+export function buildAuditPlanMetrics(tasks, options = {}) {
+    const packets = buildReviewPackets(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);
+    const largestTaskIndex = taskLineCounts.reduce((largest, value, index) => (value > taskLineCounts[largest] ? index : largest), 0);
+    const largestPacket = packets.reduce((largest, packet) => !largest || packet.total_lines > largest.total_lines ? packet : largest, undefined);
+    const taskFileReferences = tasks.reduce((sum, task) => sum + task.file_paths.length, 0);
+    const uniqueFiles = new Set(tasks.flatMap((task) => task.file_paths));
+    const lensTaskCounts = {};
+    const priorityTaskCounts = {
+        high: 0,
+        medium: 0,
+        low: 0,
+    };
+    for (const task of tasks) {
+        lensTaskCounts[task.lens] = (lensTaskCounts[task.lens] ?? 0) + 1;
+        priorityTaskCounts[normalizePriority(task.priority)] += 1;
+    }
+    return {
+        generated_at: (options.generatedAt ?? new Date()).toISOString(),
+        task_count: tasks.length,
+        packet_count: packets.length,
+        estimated_agent_reduction: Math.max(0, tasks.length - packets.length),
+        estimated_agent_reduction_ratio: tasks.length === 0 ? 0 : Math.max(0, tasks.length - packets.length) / tasks.length,
+        unique_file_count: uniqueFiles.size,
+        task_file_reference_count: taskFileReferences,
+        repeated_file_reference_count: Math.max(0, taskFileReferences - uniqueFiles.size),
+        total_task_lines: totalTaskLines,
+        total_packet_lines: totalPacketLines,
+        repeated_line_reference_count: Math.max(0, totalTaskLines - totalPacketLines),
+        min_task_lines: taskLineCounts.length > 0 ? Math.min(...taskLineCounts) : 0,
+        max_task_lines: taskLineCounts.length > 0 ? Math.max(...taskLineCounts) : 0,
+        average_task_lines: taskLineCounts.length > 0 ? totalTaskLines / taskLineCounts.length : 0,
+        largest_task_id: tasks[largestTaskIndex]?.task_id,
+        largest_packet_id: largestPacket?.packet_id,
+        lens_task_counts: lensTaskCounts,
+        priority_task_counts: priorityTaskCounts,
+        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,
+            max_tasks_per_packet: packets.length > 0 ? Math.max(...packets.map((packet) => packet.task_ids.length)) : 0,
+            max_files_per_packet: packets.length > 0 ? Math.max(...packets.map((packet) => packet.file_paths.length)) : 0,
+        },
+    };
+}

package/dist/orchestrator/selectiveDeepening.d.ts

@@ -0,0 +1,14 @@
+import type { AuditResult, AuditTask } from "../types.js";
+import type { RuntimeValidationReport, RuntimeValidationTaskManifest } from "../types/runtimeValidation.js";
+export interface BuildSelectiveDeepeningTaskOptions {
+    existingTasks?: AuditTask[];
+    results: AuditResult[];
+    lineIndex?: Record<string, number>;
+    runtimeValidationTasks?: RuntimeValidationTaskManifest;
+    runtimeValidationReport?: RuntimeValidationReport;
+    maxTasks?: number;
+}
+export declare function buildSelectiveDeepeningTasks(options: BuildSelectiveDeepeningTaskOptions): AuditTask[];
+export declare const selectiveDeepeningTestUtils: {
+    DEEPENING_TAG: string;
+};