auditor-lambda 0.3.38 → 0.3.40

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { createReadStream, existsSync } from "node:fs";
 import { Buffer } from "node:buffer";
 import { createHash } from "node:crypto";
@@ -22,6 +22,7 @@ import { buildAuditReportModel, renderAuditReportMarkdown, } from "./reporting/s
 import { deriveAuditState } from "./orchestrator/state.js";
 import { advanceAudit } from "./orchestrator/advance.js";
 import { decideNextStep } from "./orchestrator/nextStep.js";
+import { renderDesignReviewPrompt } from "./orchestrator/designReviewPrompt.js";
 import { createFreshSessionProvider, resolveFreshSessionProviderName, } from "./providers/index.js";
 import { appendRunLedgerEntry, loadRunLedger } from "./supervisor/runLedger.js";
 import { buildAuditCodeHandoff, writeAuditCodeHandoffArtifacts, } from "./supervisor/operatorHandoff.js";
@@ -1038,6 +1039,32 @@ async function runDeterministicForNextStep(params) {
                     : join(params.artifactsDir, "audit-report.md"),
             };
         }
+        if (decision.selected_executor === "design_review") {
+            const findingsPath = join(params.artifactsDir, "incoming", "design-review-findings.json");
+            let reviewFindings;
+            try {
+                reviewFindings = await readJsonFile(findingsPath);
+            }
+            catch (error) {
+                if (!isFileMissingError(error))
+                    throw error;
+            }
+            if (reviewFindings && Array.isArray(reviewFindings)) {
+                const existing = bundle.design_assessment;
+                if (existing) {
+                    existing.review_findings = reviewFindings;
+                    existing.reviewed = true;
+                    await writeJsonFile(join(params.artifactsDir, "design_assessment.json"), existing);
+                    await unlink(findingsPath).catch(() => { });
+                    continue;
+                }
+            }
+            return {
+                kind: "design_review",
+                state,
+                bundle,
+            };
+        }
         if (decision.selected_executor === "agent") {
             return {
                 kind: "semantic_review",
@@ -1177,6 +1204,38 @@ async function cmdNextStep(argv) {
         console.log(JSON.stringify(step, null, 2));
         return;
     }
+    if (result.kind === "design_review") {
+        const designReviewResultsPath = join(artifactsDir, "incoming", "design-review-findings.json");
+        await mkdir(join(artifactsDir, "incoming"), { recursive: true });
+        const continueCommand = nextStepCommand(root, artifactsDir);
+        const prompt = renderDesignReviewPrompt(result.bundle);
+        const fullPrompt = [
+            prompt,
+            "## Results path",
+            "",
+            `Write the JSON array of findings to:`,
+            "",
+            `  ${designReviewResultsPath}`,
+            "",
+            `Then run: ${continueCommand}`,
+            "",
+        ].join("\n");
+        const step = await writeCurrentStep({
+            artifactsDir,
+            stepKind: "design_review",
+            status: "ready",
+            runId: null,
+            allowedCommands: [continueCommand],
+            stopCondition: "Write design review findings to the results path, then run next-step.",
+            repoRoot: root,
+            artifactPaths: {
+                design_review_results: designReviewResultsPath,
+            },
+            prompt: fullPrompt,
+        });
+        console.log(JSON.stringify(step, null, 2));
+        return;
+    }
     if (!hostCanDispatch) {
         const singleTaskPromptPath = join(artifactsDir, "dispatch", "current-single-task-prompt.md");
         const workerCommand = renderCommand(result.activeReviewRun.worker_command);
@@ -2083,6 +2142,7 @@ async function cmdWorkerRun(argv) {
     }
 }
 const DISPATCH_RESULT_MAP_FILENAME = "dispatch-result-map.json";
+const ACTIVE_DISPATCH_FILENAME = "active-dispatch.json";
 function dispatchResultMapPath(runDir) {
     return join(runDir, DISPATCH_RESULT_MAP_FILENAME);
 }
@@ -2378,6 +2438,10 @@ async function prepareDispatchArtifacts(params) {
                     .map(([key, value]) => `input.${key}: ${value}`)
                 : [];
             const isLensVerification = task.tags?.includes("lens_verification") ?? false;
+            const coverageTemplate = task.file_paths.map((path) => ({
+                path,
+                total_lines: task.file_line_counts?.[path] ?? lineIndex[path] ?? 0,
+            }));
             return [
                 `### ${task.task_id}`,
                 `unit_id: ${task.unit_id}`,
@@ -2398,6 +2462,11 @@ async function prepareDispatchArtifacts(params) {
                     ]
                     : []),
                 "",
+                "file_coverage (copy exactly into your AuditResult for this task):",
+                "```json",
+                JSON.stringify(coverageTemplate),
+                "```",
+                "",
             ];
         });
         const submitCommand = `"${process.execPath}" "${join(packageRoot, "audit-code.mjs")}" submit-packet ` +
@@ -2442,7 +2511,7 @@ async function prepareDispatchArtifacts(params) {
             "  unit_id       copy from the task metadata",
             "  pass_id       copy from the task metadata",
             "  lens          copy from the task metadata",
-            "  file_coverage [{path, total_lines}] - one entry per assigned file; use the line counts listed above",
+            "  file_coverage [{path, total_lines}] - copy the exact template from each task section above",
             "  findings      [] or array of finding objects",
             "",
             "Lens verification tasks:",
@@ -2555,6 +2624,14 @@ async function prepareDispatchArtifacts(params) {
     if (warningsPath) {
         await writeJsonFile(warningsPath, warnings);
     }
+    const activeDispatch = {
+        run_id: runId,
+        created_at: new Date().toISOString(),
+        packet_count: plan.length,
+        task_count: orderedTasks.length,
+        status: "active",
+    };
+    await writeJsonFile(join(artifactsDir, ACTIVE_DISPATCH_FILENAME), activeDispatch);
     return {
         run_id: runId,
         dispatch_plan_path: dispatchPlanPath,
@@ -2602,12 +2679,23 @@ async function cmdSubmitPacket(argv) {
     if (!resultMap) {
         throw new Error(`No ${DISPATCH_RESULT_MAP_FILENAME} found for run ${runId}; run prepare-dispatch first.`);
     }
-    const packetEntries = resultMap.entries.filter((entry) => entry.packet_id === packetId);
+    let packetEntries = resultMap.entries.filter((entry) => entry.packet_id === packetId);
+    let resolvedPacketId = packetId;
     if (packetEntries.length === 0) {
-        throw new Error(`Unknown packet_id '${packetId}' for run ${runId}.`);
+        const trimmed = packetId.trim();
+        packetEntries = resultMap.entries.filter((entry) => entry.packet_id.trim().toLowerCase() === trimmed.toLowerCase());
+        if (packetEntries.length > 0) {
+            resolvedPacketId = packetEntries[0].packet_id;
+            process.stderr.write(`[submit-packet] Resolved packet_id '${packetId}' → '${resolvedPacketId}' (case/whitespace normalization)\n`);
+        }
+    }
+    if (packetEntries.length === 0) {
+        const knownIds = [...new Set(resultMap.entries.map((e) => e.packet_id))];
+        throw new Error(`Unknown packet_id '${packetId}' for run ${runId}.\n` +
+            `Valid packet IDs: ${knownIds.join(", ")}`);
     }
     if (entriesByTaskId(packetEntries).size !== packetEntries.length) {
-        throw new Error(`Dispatch result map has duplicate task entries for packet '${packetId}'.`);
+        throw new Error(`Dispatch result map has duplicate task entries for packet '${resolvedPacketId}'.`);
     }
     const allTasks = await readJsonFile(tasksPath);
     const taskById = new Map(allTasks.map((task) => [task.task_id, task]));
@@ -2658,7 +2746,7 @@ async function cmdSubmitPacket(argv) {
             }
             seen.add(taskId);
             if (!expectedTaskIds.has(taskId)) {
-                resultErrors.push(`Result at index ${index} uses task_id '${taskId}', which is not assigned to packet '${packetId}'.`);
+                resultErrors.push(`Result at index ${index} uses task_id '${taskId}', which is not assigned to packet '${resolvedPacketId}'.`);
             }
         }
         for (const task of tasks) {
@@ -2668,7 +2756,44 @@ async function cmdSubmitPacket(argv) {
         }
     }
     if (resultErrors.length > 0) {
-        throw new Error(`submit-packet rejected ${packetId}:\n${resultErrors.join("\n")}`);
+        throw new Error(`submit-packet rejected ${resolvedPacketId}:\n${resultErrors.join("\n")}`);
+    }
+    // Check for duplicate findings against already-submitted results in this run
+    const existingFindingKeys = new Set();
+    const otherEntries = resultMap.entries.filter((e) => e.packet_id !== resolvedPacketId);
+    for (const other of otherEntries) {
+        try {
+            const existing = JSON.parse(await readFile(other.result_path, "utf8"));
+            if (existing?.findings) {
+                for (const f of existing.findings) {
+                    const key = [
+                        (f.lens ?? "").trim().toLowerCase(),
+                        (f.category ?? "").trim().toLowerCase(),
+                        (f.title ?? "").trim().toLowerCase(),
+                        f.affected_files?.[0]?.path ?? "",
+                    ].join("|");
+                    existingFindingKeys.add(key);
+                }
+            }
+        }
+        catch { /* file doesn't exist yet or invalid — skip */ }
+    }
+    let dupCount = 0;
+    for (const result of payload) {
+        for (const f of result.findings ?? []) {
+            const key = [
+                (f.lens ?? "").trim().toLowerCase(),
+                (f.category ?? "").trim().toLowerCase(),
+                (f.title ?? "").trim().toLowerCase(),
+                f.affected_files?.[0]?.path ?? "",
+            ].join("|");
+            if (existingFindingKeys.has(key)) {
+                dupCount++;
+            }
+        }
+    }
+    if (dupCount > 0) {
+        process.stderr.write(`[submit-packet] Warning: ${dupCount} finding(s) appear to duplicate findings from other packets in this run.\n`);
     }
     const entryByTaskId = entriesByTaskId(packetEntries);
     for (const result of payload) {
@@ -2681,9 +2806,10 @@ async function cmdSubmitPacket(argv) {
     const findingCount = payload.reduce((sum, result) => sum + result.findings.length, 0);
     console.log(JSON.stringify({
         run_id: runId,
-        packet_id: packetId,
+        packet_id: resolvedPacketId,
         accepted_count: payload.length,
         finding_count: findingCount,
+        ...(dupCount > 0 ? { duplicate_warning_count: dupCount } : {}),
     }, null, 2));
 }
 async function cmdMergeAndIngest(argv) {
@@ -2722,11 +2848,24 @@ async function cmdMergeAndIngest(argv) {
     const failing = [];
     const seenTaskIds = new Set();
     let spuriousFileCount = 0;
+    const fallbackByTaskId = new Map();
     for (const filename of files) {
         const filePath = resolve(join(taskResultsDir, filename));
         if (!expectedPaths.has(filePath)) {
             spuriousFileCount++;
-            process.stderr.write(`[merge-and-ingest] Warning: ignoring unexpected file in task-results/: ${filename}\n`);
+            try {
+                const raw = await readFile(filePath, "utf8");
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    const tid = typeof parsed.task_id === "string"
+                        ? String(parsed.task_id) : undefined;
+                    if (tid && !fallbackByTaskId.has(tid)) {
+                        fallbackByTaskId.set(tid, parsed);
+                    }
+                }
+            }
+            catch { /* not parseable — skip */ }
+            process.stderr.write(`[merge-and-ingest] Warning: unexpected file in task-results/: ${filename}\n`);
         }
     }
     for (const task of allTasks) {
@@ -2745,15 +2884,23 @@ async function cmdMergeAndIngest(argv) {
         }
         catch (e) {
             if (isFileMissingError(e)) {
-                failing.push({
-                    task_id: task.task_id,
-                    errors: ["Missing audit result for assigned task."],
-                });
+                const fallback = fallbackByTaskId.get(task.task_id);
+                if (fallback) {
+                    process.stderr.write(`[merge-and-ingest] Recovered result for '${task.task_id}' from unexpected file (matched by task_id)\n`);
+                    obj = fallback;
+                }
+                else {
+                    failing.push({
+                        task_id: task.task_id,
+                        errors: ["Missing audit result for assigned task."],
+                    });
+                    continue;
+                }
             }
             else {
                 failing.push({ task_id: task.task_id, errors: [`Invalid JSON: ${e.message}`] });
+                continue;
             }
-            continue;
         }
         const record = obj && typeof obj === "object" && !Array.isArray(obj)
             ? obj
@@ -2784,45 +2931,87 @@ async function cmdMergeAndIngest(argv) {
         }
     }
     await writeJsonFile(auditResultsPath, passing);
+    const failedTasksPath = join(runDir, "failed-tasks.json");
     if (failing.length > 0) {
-        const failedTasksPath = join(runDir, "failed-tasks.json");
         await writeJsonFile(failedTasksPath, failing);
-        throw new Error(`${failing.length} assigned task result(s) were missing or invalid; blocked before ingestion. See ${failedTasksPath}`);
+    }
+    if (passing.length === 0 && failing.length > 0) {
+        throw new Error(`All ${failing.length} assigned task result(s) were missing or invalid; blocked before ingestion. See ${failedTasksPath}`);
     }
     const findingCount = passing.reduce((sum, result) => sum + result.findings.length, 0);
-    const result = await runAuditStep({
-        root: workerTask.repo_root,
-        artifactsDir,
-        preferredExecutor: "result_ingestion_executor",
-        auditResultsPath,
-    });
-    const updatedPendingTasks = await addFileLineCountHints(workerTask.repo_root, buildPendingAuditTasks(result.updated_bundle));
-    await writeJsonFile(tasksPath, updatedPendingTasks);
+    let result = null;
+    if (passing.length > 0) {
+        result = await runAuditStep({
+            root: workerTask.repo_root,
+            artifactsDir,
+            preferredExecutor: "result_ingestion_executor",
+            auditResultsPath,
+        });
+        const updatedPendingTasks = await addFileLineCountHints(workerTask.repo_root, buildPendingAuditTasks(result.updated_bundle));
+        await writeJsonFile(tasksPath, updatedPendingTasks);
+    }
+    const activeDispatchPath = join(artifactsDir, ACTIVE_DISPATCH_FILENAME);
+    try {
+        const dispatch = await readJsonFile(activeDispatchPath);
+        if (dispatch.run_id === runId) {
+            dispatch.status = failing.length > 0 ? "active" : "merged";
+            await writeJsonFile(activeDispatchPath, dispatch);
+        }
+    }
+    catch { /* no active dispatch file — skip */ }
+    let retryDispatchPath = null;
+    if (failing.length > 0) {
+        const failedTaskIds = new Set(failing.map((f) => f.task_id));
+        const failedPacketIds = [
+            ...new Set(resultMap.entries
+                .filter((e) => failedTaskIds.has(e.task_id))
+                .map((e) => e.packet_id)),
+        ];
+        const retryDispatch = {
+            run_id: runId,
+            retry_packet_ids: failedPacketIds,
+            failed_task_count: failing.length,
+            accepted_task_count: passing.length,
+        };
+        retryDispatchPath = join(runDir, "retry-dispatch.json");
+        await writeJsonFile(retryDispatchPath, retryDispatch);
+        process.stderr.write(`[merge-and-ingest] ${passing.length} accepted, ${failing.length} failed. ` +
+            `Retry packets: ${failedPacketIds.join(", ")}\n`);
+    }
+    const status = failing.length > 0
+        ? "partial"
+        : (result?.progress_made ? "completed" : "no_progress");
     const workerResult = buildWorkerResult({
         runId,
         obligationId: workerTask.obligation_id,
-        status: result.progress_made ? "completed" : "no_progress",
-        progressMade: result.progress_made,
-        selectedExecutor: result.selected_executor,
-        artifactsWritten: result.artifacts_written,
-        summary: result.progress_summary,
-        nextLikelyStep: result.next_likely_step,
+        status: failing.length > 0 ? "no_progress" : (result?.progress_made ? "completed" : "no_progress"),
+        progressMade: result?.progress_made ?? false,
+        selectedExecutor: result?.selected_executor ?? null,
+        artifactsWritten: result?.artifacts_written ?? [],
+        summary: result?.progress_summary ?? `${failing.length} task(s) failed`,
+        nextLikelyStep: result?.next_likely_step ?? null,
         errors: [],
     });
     await writeJsonFile(workerTask.result_path, workerResult);
     console.log(JSON.stringify({
         run_id: runId,
-        status: workerResult.status,
+        status,
         accepted_count: passing.length,
-        rejected_count: 0,
+        rejected_count: failing.length,
         spurious_file_count: spuriousFileCount,
         finding_count: findingCount,
         audit_results_path: auditResultsPath,
-        selected_executor: workerResult.selected_executor,
-        progress_made: workerResult.progress_made,
-        progress_summary: workerResult.summary,
-        next_likely_step: workerResult.next_likely_step,
+        ...(retryDispatchPath ? { retry_dispatch_path: retryDispatchPath } : {}),
+        ...(result ? {
+            selected_executor: workerResult.selected_executor,
+            progress_made: workerResult.progress_made,
+            progress_summary: workerResult.summary,
+            next_likely_step: workerResult.next_likely_step,
+        } : {}),
     }, null, 2));
+    if (failing.length > 0) {
+        process.exitCode = 2;
+    }
 }
 async function cmdValidateResult(argv) {
     const rawRunId = getFlag(argv, "--run-id");
@@ -3298,6 +3487,69 @@ async function cmdQuota(argv) {
         quota_state_path: getQuotaStatePath(),
     }, null, 2));
 }
+async function cmdDispatchStatus(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const activeDispatchPath = join(artifactsDir, ACTIVE_DISPATCH_FILENAME);
+    let activeDispatch = null;
+    try {
+        activeDispatch = await readJsonFile(activeDispatchPath);
+    }
+    catch (e) {
+        if (!isFileMissingError(e))
+            throw e;
+    }
+    if (!activeDispatch) {
+        console.log(JSON.stringify({ status: "no_active_dispatch" }, null, 2));
+        return;
+    }
+    const runDir = join(artifactsDir, "runs", activeDispatch.run_id);
+    const resultMap = await loadDispatchResultMap(runDir);
+    if (!resultMap) {
+        console.log(JSON.stringify({
+            status: "missing_result_map",
+            run_id: activeDispatch.run_id,
+        }, null, 2));
+        return;
+    }
+    const packetIds = [...new Set(resultMap.entries.map((e) => e.packet_id))];
+    const packetStatus = [];
+    for (const pid of packetIds) {
+        if (pid === "__prior_dispatch__")
+            continue;
+        const entries = resultMap.entries.filter((e) => e.packet_id === pid);
+        let completed = 0;
+        const missing = [];
+        for (const entry of entries) {
+            try {
+                await readFile(entry.result_path, "utf8");
+                completed++;
+            }
+            catch {
+                missing.push(entry.task_id);
+            }
+        }
+        packetStatus.push({
+            packet_id: pid,
+            task_count: entries.length,
+            completed_count: completed,
+            missing_task_ids: missing,
+        });
+    }
+    const totalTasks = packetStatus.reduce((s, p) => s + p.task_count, 0);
+    const completedTasks = packetStatus.reduce((s, p) => s + p.completed_count, 0);
+    const completedPackets = packetStatus.filter((p) => p.missing_task_ids.length === 0).length;
+    console.log(JSON.stringify({
+        run_id: activeDispatch.run_id,
+        dispatch_status: activeDispatch.status,
+        created_at: activeDispatch.created_at,
+        total_packets: packetStatus.length,
+        completed_packets: completedPackets,
+        total_tasks: totalTasks,
+        completed_tasks: completedTasks,
+        missing_tasks: totalTasks - completedTasks,
+        packets: packetStatus,
+    }, null, 2));
+}
 async function main(argv) {
     const command = argv[2] ?? "sample-run";
     switch (command) {
@@ -3370,9 +3622,12 @@ async function main(argv) {
         case "status":
             await cmdStatus(argv);
             return;
+        case "dispatch-status":
+            await cmdDispatchStatus(argv);
+            return;
         default:
             console.error(`Unknown command: ${command}`);
-            console.error("Available commands: sample-run, advance-audit, next-step, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, cleanup, mcp, prepare-dispatch, merge-and-ingest, submit-packet, validate-result, quota, status");
+            console.error("Available commands: sample-run, advance-audit, next-step, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, cleanup, mcp, prepare-dispatch, merge-and-ingest, submit-packet, validate-result, quota, status, dispatch-status");
             process.exitCode = 1;
     }
 }

package/dist/extractors/designAssessment.d.ts

@@ -0,0 +1,11 @@
+import type { UnitManifest } from "../types.js";
+import type { DesignAssessment } from "../types/designAssessment.js";
+import type { GraphBundle } from "../types/graph.js";
+import type { CriticalFlowManifest } from "../types/flows.js";
+import type { RiskRegister } from "../types/risk.js";
+export declare function buildDesignAssessment(params: {
+    unitManifest: UnitManifest;
+    graphBundle: GraphBundle;
+    criticalFlows: CriticalFlowManifest;
+    riskRegister: RiskRegister;
+}): DesignAssessment;

package/dist/extractors/designAssessment.js

@@ -0,0 +1,254 @@
+let nextFindingId = 1;
+function findingId() {
+    return `DA-${String(nextFindingId++).padStart(3, "0")}`;
+}
+function allEdges(graphBundle) {
+    const edges = [];
+    for (const [key, value] of Object.entries(graphBundle.graphs)) {
+        if (key === "routes" || !Array.isArray(value))
+            continue;
+        for (const edge of value) {
+            if (edge && typeof edge.from === "string" && typeof edge.to === "string") {
+                edges.push(edge);
+            }
+        }
+    }
+    return edges;
+}
+function detectCycles(edges) {
+    const adjacency = new Map();
+    for (const edge of edges) {
+        if (!adjacency.has(edge.from))
+            adjacency.set(edge.from, new Set());
+        adjacency.get(edge.from).add(edge.to);
+    }
+    const cycles = [];
+    const visited = new Set();
+    const stack = new Set();
+    function dfs(node, path) {
+        if (stack.has(node)) {
+            const cycleStart = path.indexOf(node);
+            if (cycleStart >= 0) {
+                cycles.push(path.slice(cycleStart));
+            }
+            return;
+        }
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        stack.add(node);
+        path.push(node);
+        for (const neighbor of adjacency.get(node) ?? []) {
+            dfs(neighbor, path);
+        }
+        path.pop();
+        stack.delete(node);
+    }
+    for (const node of adjacency.keys()) {
+        dfs(node, []);
+    }
+    return cycles;
+}
+function deduplicateCycles(cycles) {
+    const seen = new Set();
+    const unique = [];
+    for (const cycle of cycles) {
+        const normalized = [...cycle].sort().join("\0");
+        if (!seen.has(normalized)) {
+            seen.add(normalized);
+            unique.push(cycle);
+        }
+    }
+    return unique;
+}
+function detectCycleFindings(graphBundle) {
+    const edges = allEdges(graphBundle);
+    const cycles = deduplicateCycles(detectCycles(edges));
+    if (cycles.length === 0)
+        return [];
+    return cycles.slice(0, 10).map((cycle) => ({
+        id: findingId(),
+        title: `Dependency cycle: ${cycle.length} modules`,
+        category: "dependency_cycle",
+        severity: cycle.length > 4 ? "high" : "medium",
+        confidence: "high",
+        lens: "architecture",
+        summary: `Circular dependency among ${cycle.join(" → ")} → ${cycle[0]}. Cycles increase coupling, complicate testing, and can cause initialization-order bugs.`,
+        affected_files: cycle.map((path) => ({ path })),
+        systemic: true,
+    }));
+}
+function detectHubModules(graphBundle) {
+    const edges = allEdges(graphBundle);
+    const fanIn = new Map();
+    const fanOut = new Map();
+    for (const edge of edges) {
+        fanOut.set(edge.from, (fanOut.get(edge.from) ?? 0) + 1);
+        fanIn.set(edge.to, (fanIn.get(edge.to) ?? 0) + 1);
+    }
+    const allNodes = new Set([...fanIn.keys(), ...fanOut.keys()]);
+    const hubThreshold = Math.max(8, Math.ceil(allNodes.size * 0.15));
+    const findings = [];
+    for (const node of allNodes) {
+        const inCount = fanIn.get(node) ?? 0;
+        const outCount = fanOut.get(node) ?? 0;
+        if (inCount >= hubThreshold && outCount >= hubThreshold) {
+            findings.push({
+                id: findingId(),
+                title: `Hub module: ${node}`,
+                category: "hub_module",
+                severity: "medium",
+                confidence: "high",
+                lens: "architecture",
+                summary: `${node} has ${inCount} incoming and ${outCount} outgoing dependencies. Hub modules become change bottlenecks and make the dependency graph fragile.`,
+                affected_files: [{ path: node }],
+                systemic: true,
+            });
+        }
+    }
+    return findings;
+}
+function detectOrphanUnits(unitManifest, graphBundle) {
+    const edges = allEdges(graphBundle);
+    const connected = new Set();
+    for (const edge of edges) {
+        connected.add(edge.from);
+        connected.add(edge.to);
+    }
+    if (connected.size === 0)
+        return [];
+    const orphans = [];
+    for (const unit of unitManifest.units) {
+        const hasConnection = unit.files.some((file) => connected.has(file));
+        if (!hasConnection && unit.files.length > 0) {
+            orphans.push(unit.unit_id);
+        }
+    }
+    if (orphans.length === 0)
+        return [];
+    if (orphans.length > unitManifest.units.length * 0.5)
+        return [];
+    return [{
+            id: findingId(),
+            title: `${orphans.length} orphan unit(s) with no graph connections`,
+            category: "orphan_units",
+            severity: "low",
+            confidence: "medium",
+            lens: "architecture",
+            summary: `Units [${orphans.join(", ")}] have no import, call, or reference edges in the dependency graph. They may be dead code, or the graph extraction missed their connections.`,
+            affected_files: orphans.map((id) => {
+                const unit = unitManifest.units.find((u) => u.unit_id === id);
+                return { path: unit?.files[0] ?? id };
+            }),
+            systemic: true,
+        }];
+}
+function detectRiskConcentration(riskRegister, unitManifest) {
+    if (riskRegister.items.length < 4)
+        return [];
+    const sorted = [...riskRegister.items].sort((a, b) => b.risk_score - a.risk_score);
+    const topQuartileSize = Math.max(1, Math.ceil(sorted.length * 0.25));
+    const topQuartile = sorted.slice(0, topQuartileSize);
+    const totalRisk = sorted.reduce((sum, item) => sum + item.risk_score, 0);
+    const topRisk = topQuartile.reduce((sum, item) => sum + item.risk_score, 0);
+    if (totalRisk === 0)
+        return [];
+    const concentration = topRisk / totalRisk;
+    if (concentration < 0.6)
+        return [];
+    return [{
+            id: findingId(),
+            title: "Risk concentrated in top quartile of units",
+            category: "risk_concentration",
+            severity: concentration > 0.8 ? "high" : "medium",
+            confidence: "high",
+            lens: "architecture",
+            summary: `${Math.round(concentration * 100)}% of total risk score is concentrated in the top ${topQuartileSize} of ${sorted.length} units: ${topQuartile.map((i) => i.unit_id).join(", ")}. Consider decomposing high-risk units or adding isolation boundaries.`,
+            affected_files: topQuartile.flatMap((item) => {
+                const unit = unitManifest.units.find((u) => u.unit_id === item.unit_id);
+                return (unit?.files ?? [item.unit_id]).map((path) => ({ path }));
+            }),
+            systemic: true,
+        }];
+}
+function detectUnitSprawl(unitManifest) {
+    if (unitManifest.units.length < 3)
+        return [];
+    const fileCounts = unitManifest.units.map((u) => u.files.length);
+    const totalFiles = fileCounts.reduce((a, b) => a + b, 0);
+    const maxFiles = Math.max(...fileCounts);
+    const findings = [];
+    const dominantUnit = unitManifest.units.find((u) => u.files.length === maxFiles);
+    if (dominantUnit && maxFiles > totalFiles * 0.5 && totalFiles > 10) {
+        findings.push({
+            id: findingId(),
+            title: `Dominant unit: ${dominantUnit.unit_id}`,
+            category: "monolith_unit",
+            severity: "medium",
+            confidence: "medium",
+            lens: "architecture",
+            summary: `Unit ${dominantUnit.unit_id} contains ${maxFiles} of ${totalFiles} files (${Math.round((maxFiles / totalFiles) * 100)}%). A single unit this large suggests insufficient decomposition.`,
+            affected_files: dominantUnit.files.slice(0, 10).map((path) => ({ path })),
+            systemic: true,
+        });
+    }
+    if (unitManifest.units.length > 50) {
+        const smallUnits = unitManifest.units.filter((u) => u.files.length === 1);
+        if (smallUnits.length > unitManifest.units.length * 0.6) {
+            findings.push({
+                id: findingId(),
+                title: "Excessive single-file units",
+                category: "unit_fragmentation",
+                severity: "low",
+                confidence: "medium",
+                lens: "architecture",
+                summary: `${smallUnits.length} of ${unitManifest.units.length} units contain only a single file. This fragmentation may indicate that the unit grouping is too granular to reflect meaningful architectural boundaries.`,
+                affected_files: smallUnits.slice(0, 5).map((u) => ({ path: u.files[0] })),
+                systemic: true,
+            });
+        }
+    }
+    return findings;
+}
+function detectFlowGaps(criticalFlows, graphBundle) {
+    const edges = allEdges(graphBundle);
+    const connected = new Set();
+    for (const edge of edges) {
+        connected.add(edge.from);
+        connected.add(edge.to);
+    }
+    const findings = [];
+    for (const flow of criticalFlows.flows) {
+        const disconnected = flow.paths.filter((path) => !connected.has(path));
+        if (disconnected.length > 0 &&
+            disconnected.length > flow.paths.length * 0.5) {
+            findings.push({
+                id: findingId(),
+                title: `Critical flow "${flow.name}" has weak graph coverage`,
+                category: "flow_gap",
+                severity: "medium",
+                confidence: "low",
+                lens: "architecture",
+                summary: `${disconnected.length} of ${flow.paths.length} files in flow "${flow.name}" have no dependency graph edges. The flow's structural integrity cannot be verified through static analysis alone.`,
+                affected_files: disconnected.map((path) => ({ path })),
+                systemic: true,
+            });
+        }
+    }
+    return findings;
+}
+export function buildDesignAssessment(params) {
+    nextFindingId = 1;
+    const findings = [
+        ...detectCycleFindings(params.graphBundle),
+        ...detectHubModules(params.graphBundle),
+        ...detectOrphanUnits(params.unitManifest, params.graphBundle),
+        ...detectRiskConcentration(params.riskRegister, params.unitManifest),
+        ...detectUnitSprawl(params.unitManifest),
+        ...detectFlowGaps(params.criticalFlows, params.graphBundle),
+    ];
+    return {
+        generated_at: new Date().toISOString(),
+        findings,
+    };
+}

package/dist/io/artifacts.d.ts

@@ -11,6 +11,7 @@ import type { RiskRegister } from "../types/risk.js";
 import type { AuditPlanMetrics, ReviewPacket } from "../types/reviewPlanning.js";
 import type { RuntimeValidationReport, RuntimeValidationTaskManifest } from "../types/runtimeValidation.js";
 import type { SurfaceManifest } from "../types/surfaces.js";
+import type { DesignAssessment } from "../types/designAssessment.js";
 import type { ToolingManifest } from "../types/toolingManifest.js";
 type ArtifactPayloadMap = {
     repo_manifest: RepoManifest;
@@ -22,6 +23,7 @@ type ArtifactPayloadMap = {
     critical_flows: CriticalFlowManifest;
     flow_coverage: FlowCoverageManifest;
     risk_register: RiskRegister;
+    design_assessment: DesignAssessment;
     coverage_matrix: CoverageMatrix;
     runtime_validation_tasks: RuntimeValidationTaskManifest;
     runtime_validation_report: RuntimeValidationReport;
@@ -60,6 +62,7 @@ export declare const ARTIFACT_DEFINITIONS: {
     readonly critical_flows: ArtifactDefinition<"critical_flows">;
     readonly flow_coverage: ArtifactDefinition<"flow_coverage">;
     readonly risk_register: ArtifactDefinition<"risk_register">;
+    readonly design_assessment: ArtifactDefinition<"design_assessment">;
     readonly coverage_matrix: ArtifactDefinition<"coverage_matrix">;
     readonly runtime_validation_tasks: ArtifactDefinition<"runtime_validation_tasks">;
     readonly runtime_validation_report: ArtifactDefinition<"runtime_validation_report">;

package/dist/io/artifacts.js

@@ -36,6 +36,7 @@ export const ARTIFACT_DEFINITIONS = {
     critical_flows: jsonArtifact("critical_flows.json", "analysis"),
     flow_coverage: jsonArtifact("flow_coverage.json", "analysis"),
     risk_register: jsonArtifact("risk_register.json", "analysis"),
+    design_assessment: jsonArtifact("design_assessment.json", "analysis"),
     coverage_matrix: jsonArtifact("coverage_matrix.json", "execution"),
     runtime_validation_tasks: jsonArtifact("runtime_validation_tasks.json", "execution"),
     runtime_validation_report: jsonArtifact("runtime_validation_report.json", "execution"),

package/dist/orchestrator/advance.js

@@ -1,7 +1,7 @@
 import { decideNextStep } from "./nextStep.js";
 import { deriveAuditState } from "./state.js";
 import { computeArtifactMetadata } from "./artifactMetadata.js";
-import { runIntakeExecutor, runStructureExecutor, runPlanningExecutor, runResultIngestionExecutor, runRuntimeValidationExecutor, runRuntimeValidationUpdateExecutor, runSynthesisExecutor, runExternalAnalyzerImportExecutor, } from "./internalExecutors.js";
+import { runIntakeExecutor, runStructureExecutor, runPlanningExecutor, runResultIngestionExecutor, runRuntimeValidationExecutor, runRuntimeValidationUpdateExecutor, runSynthesisExecutor, runDesignAssessmentExecutor, runDesignReviewAutoComplete, runExternalAnalyzerImportExecutor, } from "./internalExecutors.js";
 import { runAutoFixExecutor } from "./autoFixExecutor.js";
 import { runSyntaxResolutionExecutor } from "./syntaxResolutionExecutor.js";
 function cloneState(state) {
@@ -53,6 +53,12 @@ export async function advanceAudit(bundle, options = {}) {
             case "structure_executor":
                 run = await runStructureExecutor(bundle, options.root);
                 break;
+            case "design_assessment_executor":
+                run = runDesignAssessmentExecutor(bundle);
+                break;
+            case "design_review":
+                run = runDesignReviewAutoComplete(bundle);
+                break;
             case "planning_executor":
                 if (!options.root)
                     throw new Error("advanceAudit planning_executor requires root");

package/dist/orchestrator/dependencyMap.js

@@ -37,6 +37,7 @@ export const ARTIFACT_DEPENDENCY_MAP = {
     ],
     "unit_manifest.json": [
         "risk_register.json",
+        "design_assessment.json",
         "coverage_matrix.json",
         "audit_tasks.json",
         "audit_plan_metrics.json",
@@ -54,6 +55,7 @@ export const ARTIFACT_DEPENDENCY_MAP = {
     "critical_flows.json": [
         "flow_coverage.json",
         "risk_register.json",
+        "design_assessment.json",
         "audit_tasks.json",
         "audit_plan_metrics.json",
         "review_packets.json",
@@ -62,6 +64,9 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "runtime_validation_report.json",
         "audit-report.md",
     ],
+    "design_assessment.json": [
+        "audit-report.md",
+    ],
     "external_analyzer_results.json": [
         "coverage_matrix.json",
         "flow_coverage.json",

package/dist/orchestrator/designReviewPrompt.d.ts

@@ -0,0 +1,2 @@
+import type { ArtifactBundle } from "../io/artifacts.js";
+export declare function renderDesignReviewPrompt(bundle: ArtifactBundle): string;

package/dist/orchestrator/designReviewPrompt.js

@@ -0,0 +1,151 @@
+function summarizeUnits(bundle) {
+    const units = bundle.unit_manifest?.units ?? [];
+    if (units.length === 0)
+        return "No units identified.";
+    const lines = units.map((unit) => {
+        const lenses = unit.required_lenses.join(", ") || "none";
+        return `- ${unit.unit_id} (${unit.files.length} files, lenses: ${lenses})`;
+    });
+    return [
+        `${units.length} units:`,
+        ...lines.slice(0, 40),
+        ...(units.length > 40 ? [`  ... and ${units.length - 40} more`] : []),
+    ].join("\n");
+}
+function summarizeGraph(bundle) {
+    const graphs = bundle.graph_bundle?.graphs;
+    if (!graphs)
+        return "No dependency graph available.";
+    const counts = [];
+    for (const [kind, edges] of Object.entries(graphs)) {
+        if (Array.isArray(edges) && edges.length > 0) {
+            counts.push(`${kind}: ${edges.length} edges`);
+        }
+    }
+    if (counts.length === 0)
+        return "Dependency graph is empty.";
+    return `Dependency graph: ${counts.join(", ")}.`;
+}
+function summarizeFlows(bundle) {
+    const flows = bundle.critical_flows?.flows ?? [];
+    if (flows.length === 0)
+        return "No critical flows identified.";
+    const lines = flows.map((flow) => `- ${flow.name}: ${flow.paths.length} files, concerns: ${flow.concerns.join(", ") || "none"}`);
+    return [`${flows.length} critical flows:`, ...lines].join("\n");
+}
+function summarizeRisk(bundle) {
+    const items = bundle.risk_register?.items ?? [];
+    if (items.length === 0)
+        return "No risk items.";
+    const sorted = [...items].sort((a, b) => b.risk_score - a.risk_score);
+    const top = sorted.slice(0, 10);
+    const lines = top.map((item) => `- ${item.unit_id}: score ${item.risk_score}, signals: ${item.signals.join(", ") || "none"}`);
+    return [
+        `${items.length} risk items (top ${top.length} by score):`,
+        ...lines,
+    ].join("\n");
+}
+function summarizeSurfaces(bundle) {
+    const surfaces = bundle.surface_manifest?.surfaces ?? [];
+    if (surfaces.length === 0)
+        return "No externally reachable surfaces identified.";
+    const lines = surfaces.map((surface) => `- ${surface.id} (${surface.kind}): ${surface.entrypoint}${surface.methods?.length ? ` [${surface.methods.join(", ")}]` : ""}`);
+    return [`${surfaces.length} surfaces:`, ...lines].join("\n");
+}
+function summarizeFiles(bundle) {
+    const files = bundle.repo_manifest?.files ?? [];
+    if (files.length === 0)
+        return "No files in manifest.";
+    const byLanguage = new Map();
+    for (const file of files) {
+        const lang = file.language || "unknown";
+        byLanguage.set(lang, (byLanguage.get(lang) ?? 0) + 1);
+    }
+    const langSummary = [...byLanguage.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([lang, count]) => `${lang}: ${count}`)
+        .join(", ");
+    return `${files.length} files (${langSummary}).`;
+}
+function formatDeterministicFindings(findings) {
+    if (findings.length === 0)
+        return "No structural issues detected by deterministic analysis.";
+    const lines = findings.map((finding) => `- [${finding.severity}] ${finding.title}: ${finding.summary}`);
+    return [
+        `${findings.length} structural findings from deterministic analysis:`,
+        ...lines,
+    ].join("\n");
+}
+export function renderDesignReviewPrompt(bundle) {
+    const deterministicFindings = bundle.design_assessment?.findings ?? [];
+    return [
+        "# Project design review",
+        "",
+        "You are reviewing the overall design of this project. The deterministic audit pipeline has already analyzed the codebase structure. Your job is to provide qualitative, big-picture design observations that static analysis cannot produce.",
+        "",
+        "## Project context",
+        "",
+        `Repository: ${bundle.repo_manifest?.repository?.name ?? "unknown"}`,
+        "",
+        "### File inventory",
+        "",
+        summarizeFiles(bundle),
+        "",
+        "### Unit structure",
+        "",
+        summarizeUnits(bundle),
+        "",
+        "### Dependency graph",
+        "",
+        summarizeGraph(bundle),
+        "",
+        "### Externally reachable surfaces",
+        "",
+        summarizeSurfaces(bundle),
+        "",
+        "### Critical flows",
+        "",
+        summarizeFlows(bundle),
+        "",
+        "### Risk profile",
+        "",
+        summarizeRisk(bundle),
+        "",
+        "### Deterministic structural findings",
+        "",
+        formatDeterministicFindings(deterministicFindings),
+        "",
+        "## What to assess",
+        "",
+        "Read the project source to understand what it does and how it works, then produce findings about:",
+        "",
+        "- **Tool and library opportunities**: third-party tools, libraries, or frameworks that would improve the project. Concrete suggestions with rationale, not generic advice.",
+        "- **Architecture pattern improvements**: structural changes that would improve extensibility, testability, or maintainability. Consider whether the current abstractions match the problem domain.",
+        "- **Design simplification**: areas where the design is over-engineered or where simpler alternatives would work. Conversely, areas that are under-designed for their importance.",
+        "- **Integration and generalization**: opportunities to make the project more portable, composable, or protocol-aligned (e.g., MCP, standard APIs, plugin architectures).",
+        "- **Missing capabilities**: gaps in the design that would become pain points as the project evolves.",
+        "",
+        "## Output format",
+        "",
+        "Produce a JSON array of findings. Each finding must conform to:",
+        "",
+        "```json",
+        "{",
+        '  "id": "DR-001",',
+        '  "title": "short descriptive title",',
+        '  "category": "one of: tool_opportunity, architecture_pattern, design_simplification, integration, missing_capability",',
+        '  "severity": "one of: critical, high, medium, low, info",',
+        '  "confidence": "one of: high, medium, low",',
+        '  "lens": "architecture",',
+        '  "summary": "detailed explanation of the observation and the recommended change",',
+        '  "affected_files": [{"path": "relevant/file.ts"}],',
+        '  "systemic": true',
+        "}",
+        "```",
+        "",
+        "Write the JSON array to the design review results path provided below. Use finding IDs starting with DR-001.",
+        "",
+        "Focus on substantive, actionable observations. Prefer fewer high-quality findings over many surface-level ones.",
+        "",
+    ].join("\n");
+}

package/dist/orchestrator/executors.js

@@ -9,6 +9,16 @@ export const EXECUTOR_REGISTRY = [
         obligation_ids: ["structure_artifacts"],
         description: "Build structure artifacts such as units, surfaces, graphs, flows, and risk.",
     },
+    {
+        id: "design_assessment_executor",
+        obligation_ids: ["design_assessment_current"],
+        description: "Run deterministic structural analysis to assess overall project design.",
+    },
+    {
+        id: "design_review",
+        obligation_ids: ["design_review_completed"],
+        description: "Pause the pipeline and delegate a holistic project design review to the active LLM agent.",
+    },
     {
         id: "planning_executor",
         obligation_ids: ["planning_artifacts"],

package/dist/orchestrator/internalExecutors.d.ts

@@ -13,6 +13,8 @@ export declare function resolveRuntimeValidationSpawnCommand(command: string[],
 };
 export declare function runIntakeExecutor(bundle: ArtifactBundle, root: string): Promise<ExecutorRunResult>;
 export declare function runStructureExecutor(bundle: ArtifactBundle, root?: string): Promise<ExecutorRunResult>;
+export declare function runDesignAssessmentExecutor(bundle: ArtifactBundle): ExecutorRunResult;
+export declare function runDesignReviewAutoComplete(bundle: ArtifactBundle): 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

@@ -15,6 +15,7 @@ import { buildUnitManifest } from "./unitBuilder.js";
 import { buildRepoManifestFromFs } from "../extractors/fsIntake.js";
 import { loadIgnoreFile } from "../extractors/ignore.js";
 import { ingestAuditResults, updateAuditTaskStatuses, } from "./resultIngestion.js";
+import { buildDesignAssessment } from "../extractors/designAssessment.js";
 import { buildSelectiveDeepeningTasks } from "./selectiveDeepening.js";
 import { updateRuntimeValidationReport } from "./runtimeValidationUpdate.js";
 import { autoCompleteTrivialCoverage } from "./trivialAudit.js";
@@ -178,6 +179,47 @@ export async function runStructureExecutor(bundle, root) {
                 : ""),
     };
 }
+export function runDesignAssessmentExecutor(bundle) {
+    if (!bundle.unit_manifest ||
+        !bundle.graph_bundle ||
+        !bundle.critical_flows ||
+        !bundle.risk_register) {
+        throw new Error("Cannot run design assessment executor without structure artifacts");
+    }
+    const designAssessment = buildDesignAssessment({
+        unitManifest: bundle.unit_manifest,
+        graphBundle: bundle.graph_bundle,
+        criticalFlows: bundle.critical_flows,
+        riskRegister: bundle.risk_register,
+    });
+    return {
+        updated: {
+            ...bundle,
+            design_assessment: designAssessment,
+        },
+        artifacts_written: ["design_assessment.json"],
+        progress_summary: `Design assessment complete: ${designAssessment.findings.length} structural finding(s).`,
+    };
+}
+export function runDesignReviewAutoComplete(bundle) {
+    const existing = bundle.design_assessment;
+    if (!existing) {
+        throw new Error("Cannot auto-complete design review without design_assessment artifact");
+    }
+    const updated = {
+        ...existing,
+        reviewed: true,
+        review_findings: existing.review_findings ?? [],
+    };
+    return {
+        updated: {
+            ...bundle,
+            design_assessment: updated,
+        },
+        artifacts_written: ["design_assessment.json"],
+        progress_summary: "Design review auto-completed (host-agent review available via next-step).",
+    };
+}
 export async function runPlanningExecutor(bundle, root, lineIndex = {}) {
     if (!bundle.repo_manifest) {
         throw new Error("Cannot run planning executor without repo_manifest");
@@ -409,6 +451,7 @@ export function runSynthesisExecutor(bundle, results) {
         coverageMatrix: bundle.coverage_matrix,
         runtimeValidationReport: bundle.runtime_validation_report,
         externalAnalyzerResults: bundle.external_analyzer_results,
+        designAssessment: bundle.design_assessment,
     });
     return {
         updated: {

package/dist/orchestrator/nextStep.js

@@ -6,6 +6,8 @@ const PRIORITY = [
     "auto_fixes_applied",
     "syntax_resolved",
     "structure_artifacts",
+    "design_assessment_current",
+    "design_review_completed",
     "planning_artifacts",
     "audit_tasks_completed",
     "audit_results_ingested",

package/dist/orchestrator/state.js

@@ -29,6 +29,8 @@ export function deriveAuditState(bundle) {
         "critical_flows.json",
         "risk_register.json",
     ], structureReady)));
+    obligations.push(obligation("design_assessment_current", staleOrSatisfied(staleArtifacts, ["design_assessment.json"], has(bundle.design_assessment))));
+    obligations.push(obligation("design_review_completed", bundle.design_assessment?.reviewed ? "satisfied" : "missing"));
     const planningReady = has(bundle.coverage_matrix) &&
         has(bundle.flow_coverage) &&
         has(bundle.runtime_validation_tasks) &&

package/dist/reporting/mergeFindings.d.ts

@@ -1,4 +1,5 @@
 import type { AuditResult, Finding } from "../types.js";
+import type { DesignAssessment } from "../types/designAssessment.js";
 import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
 import type { RuntimeValidationReport } from "../types/runtimeValidation.js";
-export declare function mergeFindings(results: AuditResult[], runtimeReport?: RuntimeValidationReport, externalAnalyzerResults?: ExternalAnalyzerResults): Finding[];
+export declare function mergeFindings(results: AuditResult[], runtimeReport?: RuntimeValidationReport, externalAnalyzerResults?: ExternalAnalyzerResults, designAssessment?: DesignAssessment): Finding[];

package/dist/reporting/mergeFindings.js

@@ -236,8 +236,20 @@ function relevantExternalEvidence(finding, results) {
         .filter((item) => findingPaths.has(item.path))
         .map((item) => `external:${results.tool}:${item.path}:${item.summary}`);
 }
-export function mergeFindings(results, runtimeReport, externalAnalyzerResults) {
+export function mergeFindings(results, runtimeReport, externalAnalyzerResults, designAssessment) {
     const merged = new Map();
+    const allDesignFindings = [
+        ...(designAssessment?.findings ?? []),
+        ...(designAssessment?.review_findings ?? []),
+    ];
+    for (const finding of allDesignFindings) {
+        const key = findingKey(finding);
+        merged.set(key, {
+            ...finding,
+            affected_files: [...finding.affected_files],
+            evidence: [...(finding.evidence ?? [])],
+        });
+    }
     for (const result of results) {
         for (const finding of result.findings) {
             const key = findingKey(finding);

package/dist/reporting/synthesis.d.ts

@@ -1,4 +1,5 @@
 import type { AuditResult, CoverageMatrix, Finding, UnitManifest } from "../types.js";
+import type { DesignAssessment } from "../types/designAssessment.js";
 import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
 import type { CriticalFlowManifest } from "../types/flows.js";
 import type { GraphBundle } from "../types/graph.js";
@@ -25,5 +26,6 @@ export declare function buildAuditReportModel(params: {
     coverageMatrix?: CoverageMatrix;
     runtimeValidationReport?: RuntimeValidationReport;
     externalAnalyzerResults?: ExternalAnalyzerResults;
+    designAssessment?: DesignAssessment;
 }): AuditReportModel;
 export declare function renderAuditReportMarkdown(model: AuditReportModel): string;

package/dist/reporting/synthesis.js

@@ -32,7 +32,7 @@ function formatSeverityList(summary) {
     return parts.length > 0 ? parts.join(", ") : "none";
 }
 export function buildAuditReportModel(params) {
-    const findings = mergeFindings(params.results, params.runtimeValidationReport, params.externalAnalyzerResults);
+    const findings = mergeFindings(params.results, params.runtimeValidationReport, params.externalAnalyzerResults, params.designAssessment);
     const workBlocks = buildWorkBlocks({
         findings,
         unitManifest: params.unitManifest,

package/dist/types/designAssessment.d.ts

@@ -0,0 +1,7 @@
+import type { Finding } from "../types.js";
+export interface DesignAssessment {
+    generated_at: string;
+    findings: Finding[];
+    review_findings?: Finding[];
+    reviewed?: boolean;
+}

package/dist/types/designAssessment.js

@@ -0,0 +1 @@
+export {};

package/dist/validation/auditResults.d.ts

@@ -1,6 +1,7 @@
 import type { AuditTask } from "../types.js";
 import { type ValidationIssue } from "./basic.js";
 export type IssueSeverity = "error" | "warning";
+export declare function normalizeCoveragePath(path: string): string;
 export interface AuditResultIssue extends ValidationIssue {
     result_index: number;
     task_id: string;

package/dist/validation/auditResults.js

@@ -1,4 +1,7 @@
 import { describeValue, formatValidationIssues, isRecord, } from "./basic.js";
+export function normalizeCoveragePath(path) {
+    return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
 const REQUIRED_FINDING_FIELDS = [
     "id",
     "title",
@@ -423,6 +426,18 @@ export function validateAuditResults(results, tasks, options = {}) {
                     tasks.map((item) => item.task_id).join(", "),
             });
         }
+        const taskNormMap = new Map();
+        if (task) {
+            for (const fp of task.file_paths) {
+                taskNormMap.set(normalizeCoveragePath(fp), fp);
+            }
+        }
+        const normLineIndex = new Map();
+        if (options.lineIndex) {
+            for (const [k, v] of Object.entries(options.lineIndex)) {
+                normLineIndex.set(normalizeCoveragePath(k), v);
+            }
+        }
         const fileCoverage = result.file_coverage;
         const normalizedFileCoverage = [];
         const declaredAssignedCoveragePaths = new Set();
@@ -447,6 +462,10 @@ export function validateAuditResults(results, tasks, options = {}) {
                     });
                     continue;
                 }
+                const entryNorm = isNonEmptyString(entry.path)
+                    ? normalizeCoveragePath(entry.path)
+                    : "";
+                const canonicalPath = taskNormMap.get(entryNorm);
                 if (!isNonEmptyString(entry.path)) {
                     pushIssue(issues, {
                         result_index: i,
@@ -455,7 +474,7 @@ export function validateAuditResults(results, tasks, options = {}) {
                         message: "file_coverage entry has an empty path.",
                     });
                 }
-                else if (task && !task.file_paths.includes(entry.path)) {
+                else if (task && !canonicalPath) {
                     pushIssue(issues, {
                         result_index: i,
                         task_id: taskId,
@@ -463,7 +482,7 @@ export function validateAuditResults(results, tasks, options = {}) {
                         message: `file_coverage path '${entry.path}' is not listed in the task file_paths.`,
                     });
                 }
-                else if (seenCoveragePaths.has(entry.path)) {
+                else if (seenCoveragePaths.has(entryNorm)) {
                     pushIssue(issues, {
                         result_index: i,
                         task_id: taskId,
@@ -472,11 +491,10 @@ export function validateAuditResults(results, tasks, options = {}) {
                     });
                 }
                 else {
-                    seenCoveragePaths.add(entry.path);
+                    seenCoveragePaths.add(entryNorm);
                 }
-                if (isNonEmptyString(entry.path) &&
-                    (!task || task.file_paths.includes(entry.path))) {
-                    declaredAssignedCoveragePaths.add(entry.path);
+                if (entryNorm.length > 0 && (!task || canonicalPath)) {
+                    declaredAssignedCoveragePaths.add(canonicalPath ?? entryNorm);
                 }
                 if (!Number.isInteger(entry.total_lines)) {
                     pushIssue(issues, {
@@ -495,8 +513,8 @@ export function validateAuditResults(results, tasks, options = {}) {
                         message: "file_coverage total_lines must be zero or greater.",
                     });
                 }
-                const expectedLineCount = typeof entry.path === "string"
-                    ? options.lineIndex?.[entry.path]
+                const expectedLineCount = entryNorm.length > 0
+                    ? normLineIndex.get(entryNorm)
                     : undefined;
                 if (Number.isInteger(entry.total_lines) &&
                     typeof expectedLineCount === "number" &&
@@ -509,19 +527,19 @@ export function validateAuditResults(results, tasks, options = {}) {
                             `(expected ${expectedLineCount}, got ${entry.total_lines}).`,
                     });
                 }
-                if (isNonEmptyString(entry.path) &&
+                if (entryNorm.length > 0 &&
                     Number.isInteger(entry.total_lines) &&
                     Number(entry.total_lines) >= 0 &&
-                    (!task || task.file_paths.includes(entry.path))) {
+                    (!task || canonicalPath)) {
                     normalizedFileCoverage.push({
-                        path: entry.path,
+                        path: canonicalPath ?? entryNorm,
                         total_lines: Number(entry.total_lines),
                     });
                 }
             }
             if (task) {
                 for (const path of task.file_paths) {
-                    if (!seenCoveragePaths.has(path)) {
+                    if (!seenCoveragePaths.has(normalizeCoveragePath(path))) {
                         pushIssue(issues, {
                             result_index: i,
                             task_id: taskId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.3.38",
+  "version": "0.3.40",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",