auditor-lambda 0.3.38 → 0.3.39

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);

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/package.json

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