auditor-lambda 0.3.40 → 0.5.0

package/dist/orchestrator/graphEnrichmentExecutor.js

@@ -0,0 +1,196 @@
+import { installToCache, resolveAnalyzerDep } from "@audit-tools/shared";
+import { buildDispositionMap } from "../extractors/disposition.js";
+import { buildPathLookup } from "../extractors/graph.js";
+import { mergeAnalyzerEdges } from "../extractors/analyzers/merge.js";
+import { ANALYZER_REGISTRY } from "../extractors/analyzers/registry.js";
+import { applyEdgeReasoning, } from "./edgeReasoning.js";
+const BUCKET_BY_KIND = {
+    "ts-import": "imports",
+    "ts-reexport": "imports",
+    "ts-call": "calls",
+    "ts-extends": "references",
+    "ts-implements": "references",
+    // Python (tree-sitter) imports merge into the imports bucket alongside the
+    // regex floor's python-* edges.
+    "py-import": "imports",
+    "py-from-import": "imports",
+    // HTML/CSS (tree-sitter) resource references live with the floor's
+    // html-resource-link / reference edges.
+    "html-resource": "references",
+    "css-import": "references",
+    "css-url": "references",
+};
+function bucketForKind(kind) {
+    const bucket = kind ? BUCKET_BY_KIND[kind] : undefined;
+    return bucket ?? "references";
+}
+function settingFor(analyzers, id) {
+    return analyzers?.[id] ?? "auto";
+}
+function routeSignature(route) {
+    return `${route.method ?? ""}\0${route.path}\0${route.handler}`;
+}
+function mergeRoutes(floor, analyzer) {
+    const deduped = new Map();
+    for (const route of [...floor, ...analyzer]) {
+        deduped.set(routeSignature(route), route);
+    }
+    return [...deduped.values()].sort((a, b) => a.path.localeCompare(b.path) ||
+        a.handler.localeCompare(b.handler) ||
+        (a.method ?? "").localeCompare(b.method ?? ""));
+}
+/**
+ * Resolve a dependency for actual execution (may install for ephemeral/permanent).
+ * `auto`/`repo` with an absent dependency falls back to the regex floor.
+ */
+function resolveForRun(analyzer, root, setting, cacheRoot) {
+    if (!analyzer.dependency) {
+        return { resolution: "repo" };
+    }
+    const options = cacheRoot ? { cacheRoot } : {};
+    const resolved = resolveAnalyzerDep(analyzer.dependency, root, options);
+    if (resolved.via === "repo" || resolved.via === "cache") {
+        return { resolution: resolved.via, path: resolved.path };
+    }
+    if (setting === "ephemeral" || setting === "permanent") {
+        const install = installToCache(analyzer.dependency, options);
+        if (install.ok && install.path) {
+            return { resolution: "installed", path: install.path };
+        }
+        return {
+            resolution: "absent",
+            note: `Install of '${analyzer.dependency}' failed: ${install.error ?? "unknown error"}.`,
+        };
+    }
+    return {
+        resolution: "absent",
+        note: `Dependency '${analyzer.dependency}' not resolvable; kept regex floor.`,
+    };
+}
+/**
+ * Resolve the optional graph-enrichment obligation. Layers language-analyzer
+ * edges onto the deterministic regex floor in `graph_bundle.json`
+ * (higher-confidence-kind-wins) and records provenance in
+ * `analyzer_capability.json`. With no root, or when every analyzer skips / is
+ * absent / not-applicable, the graph bundle is left byte-identical to the floor
+ * and only the marker is written.
+ */
+export async function runGraphEnrichmentExecutor(bundle, options = {}) {
+    const floor = bundle.graph_bundle;
+    if (!floor) {
+        throw new Error("Cannot run graph enrichment without graph_bundle");
+    }
+    const registry = options.registry ?? ANALYZER_REGISTRY;
+    const root = options.root;
+    const disposition = bundle.file_disposition;
+    const dispositionMap = buildDispositionMap(disposition);
+    const pathLookup = bundle.repo_manifest
+        ? buildPathLookup(bundle.repo_manifest, dispositionMap)
+        : new Map();
+    const includedFiles = [...new Set(pathLookup.values())].sort((a, b) => a.localeCompare(b));
+    const entries = [];
+    const bucketEdges = { imports: [], calls: [], references: [] };
+    const routeEdges = [];
+    const analyzersUsed = [];
+    for (const analyzer of registry) {
+        const setting = settingFor(options.analyzers, analyzer.id);
+        const supportedFiles = includedFiles.filter((file) => analyzer.supports(file));
+        if (supportedFiles.length === 0) {
+            entries.push({ id: analyzer.id, resolution: "not_applicable", setting, edges_added: 0, routes_added: 0 });
+            continue;
+        }
+        if (setting === "skip") {
+            entries.push({ id: analyzer.id, resolution: "skip", setting, edges_added: 0, routes_added: 0, note: "Analyzer disabled via session config." });
+            continue;
+        }
+        if (!root || !bundle.repo_manifest) {
+            entries.push({ id: analyzer.id, resolution: "absent", setting, edges_added: 0, routes_added: 0, note: "No repository root available for analysis." });
+            continue;
+        }
+        const run = resolveForRun(analyzer, root, setting, options.cacheRoot);
+        if (run.resolution === "absent") {
+            entries.push({ id: analyzer.id, resolution: "absent", setting, edges_added: 0, routes_added: 0, note: run.note });
+            continue;
+        }
+        let edges = [];
+        let routes = [];
+        try {
+            const output = await analyzer.analyze(supportedFiles, {
+                root,
+                repoManifest: bundle.repo_manifest,
+                disposition,
+                includedFiles,
+                pathLookup,
+                dependencyPath: run.path,
+            });
+            edges = output.edges ?? [];
+            routes = output.routes ?? [];
+        }
+        catch (error) {
+            entries.push({
+                id: analyzer.id,
+                resolution: run.resolution,
+                setting,
+                edges_added: 0,
+                routes_added: 0,
+                note: `Analyzer failed: ${error instanceof Error ? error.message : String(error)}.`,
+            });
+            continue;
+        }
+        for (const edge of edges) {
+            bucketEdges[bucketForKind(edge.kind)].push(edge);
+        }
+        routeEdges.push(...routes);
+        if (edges.length + routes.length > 0) {
+            analyzersUsed.push(analyzer.id);
+        }
+        entries.push({ id: analyzer.id, resolution: run.resolution, setting, edges_added: edges.length, routes_added: routes.length });
+    }
+    const applied = analyzersUsed.length > 0;
+    const record = {
+        status: applied ? "applied" : "omitted",
+        analyzers: entries,
+    };
+    // The graph this obligation produces: the enriched bundle when analyzers
+    // contributed, otherwise the regex floor. Phase 4B may then rewrite the
+    // reasons of low-confidence edges on whichever graph stands — the floor's
+    // heuristic edges exist regardless of analyzers.
+    const graphBundle = applied
+        ? {
+            ...floor,
+            graphs: {
+                ...floor.graphs,
+                imports: mergeAnalyzerEdges(floor.graphs.imports ?? [], bucketEdges.imports),
+                calls: mergeAnalyzerEdges(floor.graphs.calls ?? [], bucketEdges.calls),
+                references: mergeAnalyzerEdges(floor.graphs.references ?? [], bucketEdges.references),
+                ...(routeEdges.length > 0
+                    ? { routes: mergeRoutes(floor.graphs.routes ?? [], routeEdges) }
+                    : {}),
+            },
+            analyzers_used: [...new Set(analyzersUsed)].sort(),
+        }
+        : floor;
+    let reasoned = { rewritten: 0, candidates: 0 };
+    if (options.llmEdgeReasoning === true && options.edgeReasoning) {
+        reasoned = applyEdgeReasoning(graphBundle, options.edgeReasoning);
+    }
+    const graphChanged = applied || reasoned.rewritten > 0;
+    const reasonSuffix = reasoned.rewritten > 0
+        ? ` Edge reasoning rewrote ${reasoned.rewritten} reason(s).`
+        : "";
+    if (!graphChanged) {
+        return {
+            updated: { ...bundle, analyzer_capability: record },
+            artifacts_written: ["analyzer_capability.json"],
+            progress_summary: "Graph enrichment omitted; deterministic regex graph retained.",
+        };
+    }
+    const totalEdges = entries.reduce((sum, entry) => sum + entry.edges_added, 0);
+    return {
+        updated: { ...bundle, graph_bundle: graphBundle, analyzer_capability: record },
+        artifacts_written: ["graph_bundle.json", "analyzer_capability.json"],
+        progress_summary: applied
+            ? `Graph enrichment applied ${totalEdges} analyzer edge(s) from ${analyzersUsed.join(", ")}.${reasonSuffix}`
+            : `Graph enrichment omitted analyzers; edge reasoning rewrote ${reasoned.rewritten} reason(s).`,
+    };
+}

package/dist/orchestrator/internalExecutors.d.ts

@@ -2,6 +2,8 @@ import type { ArtifactBundle } from "../io/artifacts.js";
 import type { AuditResult } from "../types.js";
 import type { RuntimeValidationReport } from "../types/runtimeValidation.js";
 import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
+import type { AuditScopeManifest } from "../types/auditScope.js";
+import type { SynthesisNarrative } from "@audit-tools/shared";
 export interface ExecutorRunResult {
     updated: ArtifactBundle;
     artifacts_written: string[];
@@ -15,9 +17,18 @@ export declare function runIntakeExecutor(bundle: ArtifactBundle, root: string):
 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 runPlanningExecutor(bundle: ArtifactBundle, root: string, lineIndex?: Record<string, number>, sizeIndex?: Record<string, number>, scope?: AuditScopeManifest): Promise<ExecutorRunResult>;
 export declare function runResultIngestionExecutor(bundle: ArtifactBundle, results: AuditResult[]): ExecutorRunResult;
-export declare function runRuntimeValidationExecutor(bundle: ArtifactBundle, root: string): Promise<ExecutorRunResult>;
+export declare function runRuntimeValidationExecutor(bundle: ArtifactBundle, root: string, options?: {
+    opentoken?: boolean;
+}): Promise<ExecutorRunResult>;
 export declare function runRuntimeValidationUpdateExecutor(bundle: ArtifactBundle, updates: RuntimeValidationReport): ExecutorRunResult;
 export declare function runSynthesisExecutor(bundle: ArtifactBundle, results?: AuditResult[]): ExecutorRunResult;
+/**
+ * Resolve the optional synthesis-narrative obligation. When a host/provider
+ * narrative is supplied it is merged into the canonical findings report and the
+ * human report is re-rendered with themes/executive-summary/top-risks; without
+ * one the narrative is recorded as omitted and the deterministic report stands.
+ */
+export declare function runSynthesisNarrativeExecutor(bundle: ArtifactBundle, narrative?: SynthesisNarrative): ExecutorRunResult;
 export declare function runExternalAnalyzerImportExecutor(bundle: ArtifactBundle, externalResults: ExternalAnalyzerResults): ExecutorRunResult;

package/dist/orchestrator/internalExecutors.js

@@ -5,12 +5,13 @@ import { buildCriticalFlowManifest } from "../extractors/flows.js";
 import { buildRiskRegister } from "../extractors/risk.js";
 import { buildSurfaceManifest } from "../extractors/surfaces.js";
 import { initializeCoverageFromPlan } from "./planning.js";
+import { applyScopeToCoverage, fullAuditScope } from "./scope.js";
 import { buildFlowCoverage } from "./flowCoverage.js";
 import { buildRequeuePayload } from "./requeueCommand.js";
 import { buildRuntimeValidationTasks, discoverRuntimeValidationCommand, mergeRuntimeValidationReport, } from "./runtimeValidation.js";
-import { buildAuditReportModel, renderAuditReportMarkdown, } from "../reporting/synthesis.js";
+import { applyNarrative, buildAuditFindingsReport, buildAuditReportModel, renderAuditReportMarkdown, } from "../reporting/synthesis.js";
 import { buildChunkedAuditTasks, } from "./taskBuilder.js";
-import { buildAuditPlanMetrics, buildReviewPackets, } from "./reviewPackets.js";
+import { buildAuditPlanMetrics, buildReviewPackets, sizeIndexFromManifest, } from "./reviewPackets.js";
 import { buildUnitManifest } from "./unitBuilder.js";
 import { buildRepoManifestFromFs } from "../extractors/fsIntake.js";
 import { loadIgnoreFile } from "../extractors/ignore.js";
@@ -27,6 +28,7 @@ function appendSelectiveDeepeningTasks(params) {
         return { bundle: params.bundle, taskCount: 0, artifacts: [] };
     }
     const lineIndex = lineIndexFromTasks(params.bundle.audit_tasks);
+    const sizeIndex = sizeIndexFromManifest(params.bundle.repo_manifest);
     const selectiveDeepeningTasks = buildSelectiveDeepeningTasks({
         existingTasks: params.bundle.audit_tasks,
         results: params.results,
@@ -46,18 +48,33 @@ function appendSelectiveDeepeningTasks(params) {
             audit_plan_metrics: buildAuditPlanMetrics(auditTasks, {
                 graphBundle: params.bundle.graph_bundle,
                 lineIndex,
+                sizeIndex,
             }),
             review_packets: buildReviewPackets(auditTasks, {
                 graphBundle: params.bundle.graph_bundle,
                 lineIndex,
+                sizeIndex,
             }),
         },
         taskCount: selectiveDeepeningTasks.length,
         artifacts: ["audit_tasks.json", "audit_plan_metrics.json", "review_packets.json"],
     };
 }
-async function runCommand(command, cwd) {
-    const spawnCommand = resolveRuntimeValidationSpawnCommand(command);
+function resolveOpentokenWrap(resolved, platform = process.platform) {
+    if (platform === "win32") {
+        const shell = process.env.ComSpec ?? "cmd.exe";
+        const inner = [resolved.command, ...resolved.args]
+            .map((v) => (/^[A-Za-z0-9_./:=@+-]+$/.test(v) ? v : `"${v.replace(/(["^&|<>%])/g, "^$1")}"`))
+            .join(" ");
+        return { command: shell, args: ["/d", "/s", "/c", `opentoken wrap ${inner}`] };
+    }
+    return { command: "opentoken", args: ["wrap", resolved.command, ...resolved.args] };
+}
+async function runCommand(command, cwd, options = {}) {
+    let spawnCommand = resolveRuntimeValidationSpawnCommand(command);
+    if (options.opentoken) {
+        spawnCommand = resolveOpentokenWrap(spawnCommand);
+    }
     const displayCommand = command.join(" ");
     return await new Promise((resolve) => {
         const child = spawn(spawnCommand.command, spawnCommand.args, {
@@ -121,7 +138,7 @@ export async function runIntakeExecutor(bundle, root) {
     const repoManifest = await buildRepoManifestFromFs({
         root,
         ignore,
-        hash_files: false,
+        hash_files: true,
     });
     const disposition = buildFileDisposition(repoManifest);
     const auditableCount = disposition.files.filter((file) => !isAuditExcludedStatus(file.status)).length;
@@ -192,6 +209,11 @@ export function runDesignAssessmentExecutor(bundle) {
         criticalFlows: bundle.critical_flows,
         riskRegister: bundle.risk_register,
     });
+    const previous = bundle.design_assessment;
+    if (previous?.reviewed) {
+        designAssessment.reviewed = true;
+        designAssessment.review_findings = previous.review_findings ?? [];
+    }
     return {
         updated: {
             ...bundle,
@@ -220,10 +242,11 @@ export function runDesignReviewAutoComplete(bundle) {
         progress_summary: "Design review auto-completed (host-agent review available via next-step).",
     };
 }
-export async function runPlanningExecutor(bundle, root, lineIndex = {}) {
+export async function runPlanningExecutor(bundle, root, lineIndex = {}, sizeIndex, scope) {
     if (!bundle.repo_manifest) {
         throw new Error("Cannot run planning executor without repo_manifest");
     }
+    const resolvedSizeIndex = sizeIndex ?? sizeIndexFromManifest(bundle.repo_manifest);
     if (!bundle.file_disposition ||
         !bundle.unit_manifest ||
         !bundle.surface_manifest ||
@@ -231,9 +254,13 @@ export async function runPlanningExecutor(bundle, root, lineIndex = {}) {
         !bundle.risk_register) {
         throw new Error("Cannot run planning executor without current structure artifacts");
     }
+    const resolvedScope = scope ?? fullAuditScope();
     const externalAnalyzerResults = bundle.external_analyzer_results;
     const coverage = initializeCoverageFromPlan(bundle.repo_manifest, bundle.unit_manifest, bundle.file_disposition, externalAnalyzerResults);
     const skippedTrivialPaths = autoCompleteTrivialCoverage(coverage, lineIndex, externalAnalyzerResults);
+    // Delta scope: only seed + expanded files stay pending; the rest inherit prior
+    // completion or are excluded from this run. Full scope is a no-op.
+    applyScopeToCoverage(coverage, resolvedScope, bundle.coverage_matrix);
     const flowCoverage = buildFlowCoverage(bundle.critical_flows, coverage);
     const runtimeCommand = await discoverRuntimeValidationCommand(root);
     const runtimeValidationTasks = buildRuntimeValidationTasks({
@@ -256,15 +283,21 @@ export async function runPlanningExecutor(bundle, root, lineIndex = {}) {
     const reviewPackets = buildReviewPackets(taggedAuditTasks, {
         graphBundle: bundle.graph_bundle,
         lineIndex,
+        sizeIndex: resolvedSizeIndex,
     });
     const auditPlanMetrics = buildAuditPlanMetrics(taggedAuditTasks, {
         graphBundle: bundle.graph_bundle,
         lineIndex,
+        sizeIndex: resolvedSizeIndex,
     });
     const requeuePayload = buildRequeuePayload(coverage, bundle.critical_flows, flowCoverage, externalAnalyzerResults);
+    const scopeSummary = resolvedScope.mode === "delta"
+        ? ` Delta scope since ${resolvedScope.since}: ${resolvedScope.seed_files.length} changed file(s) + ${resolvedScope.expanded_files.length} graph neighbour(s) queued; a full audit is advised before release.`
+        : "";
     return {
         updated: {
             ...bundle,
+            scope: resolvedScope,
             coverage_matrix: coverage,
             flow_coverage: flowCoverage,
             runtime_validation_tasks: runtimeValidationTasks,
@@ -276,6 +309,7 @@ export async function runPlanningExecutor(bundle, root, lineIndex = {}) {
             audit_report: undefined,
         },
         artifacts_written: [
+            "scope.json",
             "coverage_matrix.json",
             "flow_coverage.json",
             "runtime_validation_tasks.json",
@@ -286,6 +320,7 @@ export async function runPlanningExecutor(bundle, root, lineIndex = {}) {
             "requeue_tasks.json",
         ],
         progress_summary: `Built planning artifacts; generated ${taggedAuditTasks.length} review tasks in ${reviewPackets.length} packet(s) and ${requeuePayload.task_count} requeue tasks.` +
+            scopeSummary +
             (skippedTrivialPaths.length > 0
                 ? ` Skipped ${skippedTrivialPaths.length} trivial path${skippedTrivialPaths.length === 1 ? "" : "s"} from semantic review.`
                 : "") +
@@ -354,7 +389,7 @@ export function runResultIngestionExecutor(bundle, results) {
                 : ""),
     };
 }
-export async function runRuntimeValidationExecutor(bundle, root) {
+export async function runRuntimeValidationExecutor(bundle, root, options = {}) {
     if (!bundle.runtime_validation_tasks) {
         throw new Error("Cannot execute runtime validation without runtime_validation_tasks");
     }
@@ -378,7 +413,7 @@ export async function runRuntimeValidationExecutor(bundle, root) {
             continue;
         }
         const signature = task.command.join("\0");
-        const outcome = byCommand.get(signature) ?? (await runCommand(task.command, root));
+        const outcome = byCommand.get(signature) ?? (await runCommand(task.command, root, { opentoken: options.opentoken }));
         byCommand.set(signature, outcome);
         byTaskId.set(task.id, {
             task_id: task.id,
@@ -441,10 +476,9 @@ export function runRuntimeValidationUpdateExecutor(bundle, updates) {
                 : ""),
     };
 }
-export function runSynthesisExecutor(bundle, results) {
-    const finalResults = results ?? bundle.audit_results ?? [];
-    const model = buildAuditReportModel({
-        results: finalResults,
+function buildBaseFindingsReport(bundle, results) {
+    return buildAuditFindingsReport(buildAuditReportModel({
+        results,
         unitManifest: bundle.unit_manifest,
         graphBundle: bundle.graph_bundle,
         criticalFlows: bundle.critical_flows,
@@ -452,15 +486,77 @@ export function runSynthesisExecutor(bundle, results) {
         runtimeValidationReport: bundle.runtime_validation_report,
         externalAnalyzerResults: bundle.external_analyzer_results,
         designAssessment: bundle.design_assessment,
-    });
+    }));
+}
+export function runSynthesisExecutor(bundle, results) {
+    const finalResults = results ?? bundle.audit_results ?? [];
+    // Emit the canonical machine contract and render the human report from it.
+    // No narrative yet — that is layered by the synthesis-narrative obligation.
+    const findings = buildBaseFindingsReport(bundle, finalResults);
     return {
         updated: {
             ...bundle,
             audit_results: finalResults,
-            audit_report: renderAuditReportMarkdown(model),
+            audit_findings: findings,
+            audit_report: renderAuditReportMarkdown(findings, { scope: bundle.scope }),
+        },
+        artifacts_written: ["audit-findings.json", "audit-report.md"],
+        progress_summary: `Rendered deterministic audit report and canonical findings for ${finalResults.length} audit result entries.`,
+    };
+}
+/**
+ * Resolve the optional synthesis-narrative obligation. When a host/provider
+ * narrative is supplied it is merged into the canonical findings report and the
+ * human report is re-rendered with themes/executive-summary/top-risks; without
+ * one the narrative is recorded as omitted and the deterministic report stands.
+ */
+export function runSynthesisNarrativeExecutor(bundle, narrative) {
+    const baseReport = bundle.audit_findings ??
+        buildBaseFindingsReport(bundle, bundle.audit_results ?? []);
+    const needsBaseWrite = !bundle.audit_findings;
+    const hasNarrative = Boolean(narrative &&
+        ((narrative.themes?.length ?? 0) > 0 ||
+            (narrative.executive_summary?.trim().length ?? 0) > 0 ||
+            (narrative.top_risks?.length ?? 0) > 0));
+    if (!hasNarrative) {
+        const record = {
+            status: "omitted",
+            theme_count: 0,
+            executive_summary_present: false,
+            top_risk_count: 0,
+        };
+        return {
+            updated: {
+                ...bundle,
+                audit_findings: baseReport,
+                synthesis_narrative: record,
+            },
+            artifacts_written: needsBaseWrite
+                ? ["audit-findings.json", "synthesis-narrative.json"]
+                : ["synthesis-narrative.json"],
+            progress_summary: "Synthesis narrative omitted; deterministic findings report retained.",
+        };
+    }
+    const enriched = applyNarrative(baseReport, narrative);
+    const record = {
+        status: "applied",
+        theme_count: enriched.themes?.length ?? 0,
+        executive_summary_present: (enriched.executive_summary?.trim().length ?? 0) > 0,
+        top_risk_count: enriched.top_risks?.length ?? 0,
+    };
+    return {
+        updated: {
+            ...bundle,
+            audit_findings: enriched,
+            audit_report: renderAuditReportMarkdown(enriched, { scope: bundle.scope }),
+            synthesis_narrative: record,
         },
-        artifacts_written: ["audit-report.md"],
-        progress_summary: `Rendered deterministic audit report for ${finalResults.length} audit result entries.`,
+        artifacts_written: [
+            "audit-findings.json",
+            "audit-report.md",
+            "synthesis-narrative.json",
+        ],
+        progress_summary: `Synthesis narrative applied: ${record.theme_count} theme(s), ${record.top_risk_count} top risk(s).`,
     };
 }
 export function runExternalAnalyzerImportExecutor(bundle, externalResults) {

package/dist/orchestrator/localCommands.js

@@ -1,32 +1,13 @@
 import { existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { delimiter, extname, isAbsolute, join } from "node:path";
-function isWindowsBatchCommand(path) {
-    return process.platform === "win32" && /\.(cmd|bat)$/i.test(path);
-}
-function quoteForCmd(arg) {
-    if (arg.length === 0)
-        return '""';
-    if (!/[\s"]/u.test(arg))
-        return arg;
-    return `"${arg.replace(/"/g, '""')}"`;
-}
+import { resolveExecArgv } from "@audit-tools/shared";
 function toSpawnTuple(candidate) {
-    if (!isWindowsBatchCommand(candidate.command)) {
-        return {
-            command: candidate.command,
-            args: candidate.args,
-        };
-    }
-    return {
-        command: process.env.ComSpec ?? "cmd.exe",
-        args: [
-            "/d",
-            "/s",
-            "/c",
-            [candidate.command, ...candidate.args].map(quoteForCmd).join(" "),
-        ],
-    };
+    // Shared resolver applies the single Windows `.cmd`/`.bat` wrapping impl.
+    // The candidate command is already PATH-resolved (absolute path or
+    // process.execPath), so package-manager shim mapping is a no-op here.
+    const resolved = resolveExecArgv([candidate.command, ...candidate.args]);
+    return { command: resolved[0], args: resolved.slice(1) };
 }
 function resolveFromPath(command) {
     if (command.trim().length === 0) {

package/dist/orchestrator/nextStep.d.ts

@@ -1,9 +1,10 @@
 import type { ArtifactBundle } from "../io/artifacts.js";
-import type { AuditState } from "../types/auditState.js";
+import type { AuditObligation, AuditState } from "../types/auditState.js";
 export interface NextStepDecision {
     state: AuditState;
     selected_obligation: string | null;
     selected_executor: string | null;
     reason: string;
 }
+export declare function findObligation(obligations: AuditObligation[]): AuditObligation | undefined;
 export declare function decideNextStep(bundle: ArtifactBundle): NextStepDecision;

package/dist/orchestrator/nextStep.js

@@ -6,6 +6,7 @@ const PRIORITY = [
     "auto_fixes_applied",
     "syntax_resolved",
     "structure_artifacts",
+    "graph_enrichment_current",
     "design_assessment_current",
     "design_review_completed",
     "planning_artifacts",
@@ -13,8 +14,9 @@ const PRIORITY = [
     "audit_results_ingested",
     "runtime_validation_current",
     "synthesis_current",
+    "synthesis_narrative_current",
 ];
-function findObligation(obligations) {
+export function findObligation(obligations) {
     for (const id of PRIORITY) {
         const item = obligations.find((o) => o.id === id);
         if (item && (item.state === "missing" || item.state === "stale")) {

package/dist/orchestrator/planning.d.ts

@@ -1,4 +1,4 @@
 import type { CoverageMatrix, RepoManifest, UnitManifest } from "../types.js";
-import type { FileDisposition } from "../types/disposition.js";
+import type { FileDisposition } from "@audit-tools/shared";
 import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
 export declare function initializeCoverageFromPlan(repoManifest: RepoManifest, unitManifest: UnitManifest, disposition: FileDisposition, externalAnalyzerResults?: ExternalAnalyzerResults): CoverageMatrix;

package/dist/orchestrator/requeueCommand.d.ts

@@ -1,7 +1,7 @@
 import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
 import type { CoverageMatrix } from "../types.js";
 import type { FlowCoverageManifest } from "../types/flowCoverage.js";
-import type { CriticalFlowManifest } from "../types/flows.js";
+import type { CriticalFlowManifest } from "@audit-tools/shared";
 export declare function buildRequeuePayload(matrix: CoverageMatrix, criticalFlows?: CriticalFlowManifest, flowCoverage?: FlowCoverageManifest, externalAnalyzerResults?: ExternalAnalyzerResults): {
     task_count: number;
     file_task_count: number;

package/dist/orchestrator/reviewPackets.d.ts

@@ -1,20 +1,53 @@
 import type { AuditTask } from "../types.js";
 import type { AuditPlanMetrics, ReviewPacket } from "../types/reviewPlanning.js";
-import type { GraphBundle } from "../types/graph.js";
+import type { GraphBundle, GraphEdge } from "@audit-tools/shared";
 export declare const ESTIMATED_TOKENS_PER_LINE = 4;
 export declare const ESTIMATED_PACKET_PROMPT_TOKENS = 900;
-export declare function estimateTaskGroupTokens(tasks: AuditTask[]): number;
+/**
+ * Build a path → size_bytes index from a repo manifest. Byte counts are
+ * recorded during intake, so this never reads files. Review packet token
+ * estimates are derived from these bytes (Phase 2) instead of counted lines.
+ */
+export declare function sizeIndexFromManifest(repoManifest?: {
+    files: ReadonlyArray<{
+        path: string;
+        size_bytes: number;
+    }>;
+}): Record<string, number>;
+export declare function estimateTaskGroupTokens(tasks: AuditTask[], sizeIndex?: Record<string, number>, lineIndex?: Record<string, number>): number;
+/**
+ * Fan-in / fan-out degree above which a node is treated as a hub. Exported so
+ * the Phase 3 delta-scope expansion skips the same hubs that packet planning
+ * skips, preventing scope blow-up through highly-connected modules.
+ */
+export declare const HIGH_FAN_DEGREE_THRESHOLD = 12;
 export interface BuildReviewPacketOptions {
     graphBundle?: GraphBundle;
     lineIndex?: Record<string, number>;
+    /** Path → size_bytes (from the repo manifest); drives byte-based token sizing. */
+    sizeIndex?: Record<string, number>;
     maxTasksPerPacket?: number;
-    targetPacketLines?: number;
+    /**
+     * Soft per-packet content-token budget. Defaults to
+     * DEFAULT_TARGET_PACKET_TOKENS. A packet is split when its estimated content
+     * tokens would exceed this budget.
+     */
+    targetPacketTokens?: number;
     /**
      * Available context budget in tokens (context_tokens − reserved_output_tokens).
-     * When provided, targetPacketLines is capped to fit within this budget.
+     * When provided, targetPacketTokens is capped to fit within this budget so a
+     * packet's estimated tokens never exceed it.
      */
     maxContextTokens?: number;
 }
+export declare function normalizeGraphPath(path: string): string;
+export declare function collectGraphEdges(graphBundle?: GraphBundle): GraphEdge[];
+export declare function graphEdgeConfidence(edge: GraphEdge): number;
+export interface GraphDegreeIndex {
+    fanIn: Map<string, number>;
+    fanOut: Map<string, number>;
+}
+export declare function buildGraphDegreeIndex(edges: GraphEdge[]): GraphDegreeIndex;
 export declare function buildReviewPackets(tasks: AuditTask[], options?: BuildReviewPacketOptions): ReviewPacket[];
 export declare function orderTasksForPacketReview(tasks: AuditTask[], options?: BuildReviewPacketOptions): AuditTask[];
 export declare function buildAuditPlanMetrics(tasks: AuditTask[], options?: BuildReviewPacketOptions & {