auditor-lambda 0.7.0 → 0.8.0

package/README.md

@@ -215,26 +215,6 @@ Optional backend config:
 - use `provider: "auto"` only when you want best-effort routing across installed backends
 - treat explicit provider bridges as compatibility fallback, not as the intended owner of semantic review
 
-## Current Development Focus
-
-The next implementation work is tracked in:
-
-- `docs/product.md`
-- `docs/development.md`
-- `docs/handoff.md`
-
-The short version is:
-
-- keep the packet dispatch workflow verified in real host environments
-- make graph-informed packetization observable before adding more ecosystem-specific parsers
-- consolidate graph extraction and exercise generic ownership hints for analyzer-supplied module roots
-- add deterministic Python import, package, and test/source graph support as a core language path
-- use semantic/NLP-style affinity only as low-authority context unless deterministic graph evidence supports it
-- keep generated Codex, Claude Desktop, OpenCode, VS Code, and Antigravity guidance aligned with real host behavior
-- tighten the repo-local MCP-first bootstrap where host smoke tests expose friction
-- polish provider-assisted continuation and failure guidance
-- keep schema contracts and examples easy for workers and host integrations to validate
-
 ## Build And Test
 
 ```bash
@@ -253,6 +233,5 @@ For GitHub Actions publication and npm Trusted Publishing setup, see `docs/relea
 - `docs/contracts.md`
 - `docs/release.md`
 - `docs/development.md`
-- `docs/handoff.md`
 - `docs/history.md`
 - `skills/audit-code/SKILL.md`

package/dist/cli/auditStep.js

@@ -84,7 +84,13 @@ export async function runAuditStep(options) {
         opentoken: options.opentoken,
         runLogger,
     });
-    await writeCoreArtifacts(options.artifactsDir, result.updated_bundle);
+    // Prune: result.updated_bundle is the full accumulated bundle, so an artifact
+    // an executor cleared to `undefined` must be removed from disk (not left to
+    // reload as a stale "present" artifact). Safe only because this is the
+    // authoritative per-step persist.
+    await writeCoreArtifacts(options.artifactsDir, result.updated_bundle, {
+        prune: true,
+    });
     const archivedPendingResults = await maybeArchiveLegacyPendingResults(options.auditResultsPath);
     if (archivedPendingResults) {
         result.progress_summary +=

package/dist/cli.d.ts

@@ -1,4 +1,3 @@
-export { resolveHostDispatchCapability, DIRECT_CLI_DEFAULTS, getFlag, hasFlag, getOptionalBooleanFlag, getArtifactsDir, getRootDir, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, chunkArray, getUiMode, looksLikeCliFlag, countLines, warnIfNotGitRepo, } from "./cli/args.js";
 import { getFlag, hasFlag, getArtifactsDir, getRootDir, warnIfNotGitRepo, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, chunkArray, getUiMode, looksLikeCliFlag, countLines } from "./cli/args.js";
 export declare const cliTestUtils: {
     defaults: {

package/dist/cli.js

@@ -24,8 +24,6 @@ import { getSessionConfigPath, loadSessionConfig, readSessionConfigFile, } from
 import { clearDispatchFiles, ensureSupervisorDirs, } from "./io/runArtifacts.js";
 import { runAuditCodeMcpServer } from "./mcp/server.js";
 import { scheduleWave, buildProviderModelKey, readQuotaState, resolveLimits, resolveHostActiveSubagentLimit, probeProvider, computeMaxSafeConcurrency, getQuotaStatePath, lookupDiscoveredLimits, setQuotaStateDir, } from "./quota/index.js";
-// Re-exports from extracted modules
-export { resolveHostDispatchCapability, DIRECT_CLI_DEFAULTS, getFlag, hasFlag, getOptionalBooleanFlag, getArtifactsDir, getRootDir, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, chunkArray, getUiMode, looksLikeCliFlag, countLines, warnIfNotGitRepo, } from "./cli/args.js";
 import { DIRECT_CLI_DEFAULTS, getFlag, hasFlag, fromBase64Url, taskResultPath, isCanonicalResultFilename, readStdinText, getArtifactsDir, getRootDir, warnIfNotGitRepo, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, getExplicitProvider, getHostModel, getHostMaxActiveSubagents, getQuotaProbeMode, resolveRunProviderName, chunkArray, getUiMode, looksLikeCliFlag, countLines, } from "./cli/args.js";
 import { WORKER_RESULT_CONTRACT_VERSION, buildWorkerResult, formatAuditResultValidationError, } from "./cli/workerResult.js";
 import { DISPATCH_RESULT_MAP_FILENAME, ACTIVE_DISPATCH_FILENAME, resolveRunScopedArg, loadDispatchResultMap, entriesByTaskId, buildPendingAuditTasks, prepareDispatchArtifacts, } from "./cli/dispatch.js";

package/dist/extractors/graph.js

@@ -262,6 +262,7 @@ export async function buildGraphBundleFromFs(repoManifest, root, disposition, op
     const rootPath = resolve(root);
     const dispositionMap = buildDispositionMap(disposition);
     const fileContents = {};
+    const skippedFiles = [];
     await Promise.all(repoManifest.files.map(async (file) => {
         const status = dispositionMap.get(file.path);
         if ((status && isAuditExcludedStatus(status)) ||
@@ -277,10 +278,19 @@ export async function buildGraphBundleFromFs(repoManifest, root, disposition, op
         try {
             fileContents[file.path] = await readFile(absolutePath, "utf8");
         }
-        catch {
-            // Best-effort graph extraction should not block structure planning.
+        catch (e) {
+            // Best-effort graph extraction should not block structure planning,
+            // but record the skip so a coverage gap is observable to operators.
+            skippedFiles.push({ path: file.path, error: e.code ?? String(e) });
         }
     }));
+    if (skippedFiles.length > 0) {
+        process.stderr.write("[audit-code] graph: skipped " +
+            skippedFiles.length +
+            " unreadable file(s): " +
+            skippedFiles.map((s) => s.path + " (" + s.error + ")").join(", ") +
+            "\n");
+    }
     return buildGraphBundle(repoManifest, disposition, { ...options, fileContents });
 }
 export function buildGraphBundle(repoManifest, disposition, options = {}) {

package/dist/io/artifacts.d.ts

@@ -89,7 +89,9 @@ export declare const ARTIFACT_DEFINITIONS: {
 export declare const ARTIFACT_FILE_TO_BUNDLE_KEY: Record<string, ArtifactBundleKey>;
 export declare function getArtifactValue(bundle: ArtifactBundle, artifactName: string): unknown;
 export declare function loadArtifactBundle(root: string): Promise<ArtifactBundle>;
-export declare function writeCoreArtifacts(root: string, bundle: ArtifactBundle): Promise<void>;
+export declare function writeCoreArtifacts(root: string, bundle: ArtifactBundle, options?: {
+    prune?: boolean;
+}): Promise<void>;
 export declare function cleanupIntermediateArtifacts(root: string): Promise<string[]>;
 export declare function promoteFinalAuditReport(params: {
     artifactsDir: string;

package/dist/io/artifacts.js

@@ -79,13 +79,29 @@ export async function loadArtifactBundle(root) {
     bundle.tooling_manifest = await buildToolingManifest();
     return bundle;
 }
-export async function writeCoreArtifacts(root, bundle) {
+export async function writeCoreArtifacts(root, bundle, options = {}) {
     const bundleRecord = bundle;
     for (const entry of ARTIFACT_ENTRIES) {
         const [key, definition] = entry;
         const value = bundleRecord[key];
+        const path = join(root, definition.fileName);
         if (value !== undefined) {
-            await definition.write(join(root, definition.fileName), value);
+            await definition.write(path, value);
+        }
+        else if (options.prune) {
+            // The bundle is authoritative. An executor that clears an artifact to
+            // `undefined` (to force a downstream rebuild — e.g. planning/ingestion
+            // reset audit_report) intends the file gone; if it lingers it reloads as a
+            // stale "present" artifact with no metadata entry, which deriveAuditState
+            // reads as satisfied — masking the invalidation and stranding a stale
+            // report. Only callers passing the full accumulated bundle may prune.
+            try {
+                await unlink(path);
+            }
+            catch (error) {
+                if (!isFileMissingError(error))
+                    throw error;
+            }
         }
     }
 }

package/dist/orchestrator/advance.js

@@ -1,7 +1,8 @@
 import { decideNextStep, findObligation } from "./nextStep.js";
 import { deriveAuditState } from "./state.js";
 import { computeArtifactMetadata } from "./artifactMetadata.js";
-import { runIntakeExecutor, runStructureExecutor, runPlanningExecutor, runResultIngestionExecutor, runRuntimeValidationExecutor, runRuntimeValidationUpdateExecutor, runSynthesisExecutor, runSynthesisNarrativeExecutor, runDesignAssessmentExecutor, runDesignReviewAutoComplete, runExternalAnalyzerImportExecutor, } from "./internalExecutors.js";
+import { runIntakeExecutor, runStructureExecutor, runPlanningExecutor, runResultIngestionExecutor, runRuntimeValidationExecutor, runRuntimeValidationUpdateExecutor, runDesignAssessmentExecutor, runDesignReviewAutoComplete, runExternalAnalyzerImportExecutor, } from "./internalExecutors.js";
+import { runSynthesisExecutor, runSynthesisNarrativeExecutor, } from "./synthesisExecutors.js";
 import { runAutoFixExecutor } from "./autoFixExecutor.js";
 import { runSyntaxResolutionExecutor } from "./syntaxResolutionExecutor.js";
 import { runGraphEnrichmentExecutor } from "./graphEnrichmentExecutor.js";

package/dist/orchestrator/artifactFreshness.js

@@ -15,9 +15,19 @@ export function stableStringify(value) {
         .sort(([a], [b]) => a.localeCompare(b));
     return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`).join(",")}}`;
 }
+// Artifacts that stamp a wall-clock `generated_at` on every (re)build. The
+// timestamp is provenance, not content: two rebuilds with identical data but
+// different timestamps must hash equal, or the artifact's revision churns every
+// rebuild and perpetually re-stales its downstreams (e.g. audit-report.md
+// depends on design_assessment) — a finalization-oscillation hazard.
+const GENERATED_AT_STRIPPED_ARTIFACTS = new Set([
+    "repo_manifest.json",
+    "tooling_manifest.json",
+    "audit_plan_metrics.json",
+    "design_assessment.json",
+]);
 export function normalizeForMetadataHash(artifactName, value) {
-    if ((artifactName === "repo_manifest.json" ||
-        artifactName === "tooling_manifest.json") &&
+    if (GENERATED_AT_STRIPPED_ARTIFACTS.has(artifactName) &&
         value &&
         typeof value === "object" &&
         !Array.isArray(value)) {

package/dist/orchestrator/autoFixExecutor.d.ts

@@ -1,3 +1,3 @@
 import type { ArtifactBundle } from "../io/artifacts.js";
-import type { ExecutorRunResult } from "./internalExecutors.js";
+import type { ExecutorRunResult } from "./executorResult.js";
 export declare function runAutoFixExecutor(bundle: ArtifactBundle, root: string): ExecutorRunResult;

package/dist/orchestrator/autoFixExecutor.js

@@ -49,6 +49,7 @@ export function runAutoFixExecutor(bundle, root) {
         }
     }
     const executedTools = [];
+    const toolTimings = [];
     // JS, TS, HTML, CSS, JSON, YAML, MD
     if (hasPrettierConfig(root) &&
         (extensions.has("ts") ||
@@ -61,16 +62,19 @@ export function runAutoFixExecutor(bundle, root) {
             extensions.has("yml") ||
             extensions.has("yaml") ||
             extensions.has("md"))) {
+        const prettierStart = Date.now();
         if (tryRunConfiguredFormatter(root, [
             ...resolveNodeTool(root, join("node_modules", "prettier", "bin", "prettier.cjs"), ["--write", "."], "prettier --write ."),
             { command: "prettier", args: ["--write", "."], display: "prettier --write ." },
             { command: "npx", args: ["--yes", "prettier", "--write", "."], display: "npx --yes prettier --write ." },
         ])) {
             executedTools.push("prettier");
+            toolTimings.push({ tool: "prettier", duration_ms: Date.now() - prettierStart });
         }
     }
     // Python
     if (extensions.has("py")) {
+        const blackStart = Date.now();
         if (tryRunConfiguredFormatter(root, [
             { command: "black", args: ["."], display: "black ." },
             { command: "python", args: ["-m", "black", "."], display: "python -m black ." },
@@ -78,28 +82,34 @@ export function runAutoFixExecutor(bundle, root) {
             { command: "pipx", args: ["run", "black", "."], display: "pipx run black ." },
         ])) {
             executedTools.push("black");
+            toolTimings.push({ tool: "black", duration_ms: Date.now() - blackStart });
         }
     }
     // SQL
     if (extensions.has("sql")) {
+        const sqlfluffStart = Date.now();
         if (tryRunConfiguredFormatter(root, [
             { command: "sqlfluff", args: ["fix", "--force", "."], display: "sqlfluff fix --force ." },
             { command: "uvx", args: ["sqlfluff", "fix", "--force", "."], display: "uvx sqlfluff fix --force ." },
             { command: "pipx", args: ["run", "sqlfluff", "fix", "--force", "."], display: "pipx run sqlfluff fix --force ." },
         ])) {
             executedTools.push("sqlfluff");
+            toolTimings.push({ tool: "sqlfluff", duration_ms: Date.now() - sqlfluffStart });
         }
     }
     // Go
     if (extensions.has("go")) {
+        const gofmtStart = Date.now();
         if (tryRunConfiguredFormatter(root, [
             { command: "gofmt", args: ["-w", "."], display: "gofmt -w ." },
         ])) {
             executedTools.push("gofmt");
+            toolTimings.push({ tool: "gofmt", duration_ms: Date.now() - gofmtStart });
         }
     }
     const resultsArtifact = {
         executed_tools: executedTools,
+        tool_timings: toolTimings,
         timestamp: new Date().toISOString(),
     };
     return {

package/dist/orchestrator/executorResult.d.ts

@@ -0,0 +1,12 @@
+import type { ArtifactBundle } from "../io/artifacts.js";
+/**
+ * Uniform result of running one audit executor: the updated artifact bundle, the
+ * artifact filenames it wrote (which drive metadata/staleness bookkeeping in
+ * advanceAudit), and a one-line human progress summary. Shared by every executor
+ * module so they need not depend on the internalExecutors barrel.
+ */
+export interface ExecutorRunResult {
+    updated: ArtifactBundle;
+    artifacts_written: string[];
+    progress_summary: string;
+}

package/dist/orchestrator/executorResult.js

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

package/dist/orchestrator/fileIntegrity.d.ts

@@ -2,6 +2,7 @@ import type { RepoManifest } from "../types.js";
 export interface FileIntegrityResult {
     changed_files: string[];
     missing_files: string[];
+    io_errors: string[];
     is_clean: boolean;
 }
 export declare function checkFileIntegrity(root: string, manifest: RepoManifest, scope?: string[]): Promise<FileIntegrityResult>;

package/dist/orchestrator/fileIntegrity.js

@@ -9,6 +9,7 @@ async function hashFile(absolutePath) {
 export async function checkFileIntegrity(root, manifest, scope) {
     const changed = [];
     const missing = [];
+    const ioErrors = [];
     const scopeSet = scope ? new Set(scope) : null;
     const files = scopeSet
         ? manifest.files.filter((f) => scopeSet.has(f.path))
@@ -29,13 +30,21 @@ export async function checkFileIntegrity(root, manifest, scope) {
                 changed.push(record.path);
             }
         }
-        catch {
-            missing.push(record.path);
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT") {
+                missing.push(record.path);
+            }
+            else {
+                console.warn(`fileIntegrity: I/O error on ${record.path}: ${code ?? String(err)}`);
+                ioErrors.push(record.path);
+            }
         }
     }
     return {
         changed_files: changed,
         missing_files: missing,
-        is_clean: changed.length === 0 && missing.length === 0,
+        io_errors: ioErrors,
+        is_clean: changed.length === 0 && missing.length === 0 && ioErrors.length === 0,
     };
 }

package/dist/orchestrator/graphEnrichmentExecutor.d.ts

@@ -1,5 +1,5 @@
 import type { ArtifactBundle } from "../io/artifacts.js";
-import type { ExecutorRunResult } from "./internalExecutors.js";
+import type { ExecutorRunResult } from "./executorResult.js";
 import type { AnalyzerSetting } from "@audit-tools/shared";
 import type { LanguageAnalyzer } from "../extractors/analyzers/types.js";
 import { type EdgeReasoningResults } from "./edgeReasoning.js";

package/dist/orchestrator/graphEnrichmentExecutor.js

@@ -133,7 +133,9 @@ export async function runGraphEnrichmentExecutor(bundle, options = {}) {
                 setting,
                 edges_added: 0,
                 routes_added: 0,
-                note: `Analyzer failed: ${error instanceof Error ? error.message : String(error)}.`,
+                note: error instanceof Error
+                    ? `Analyzer failed [${error.name}]: ${error.message}${error.stack ? ` — stack: ${error.stack.split("\n").slice(0, 4).join(" | ")}` : ""}`
+                    : `Analyzer failed: ${String(error)}.`,
             });
             continue;
         }

package/dist/orchestrator/internalExecutors.d.ts

@@ -3,16 +3,7 @@ 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[];
-    progress_summary: string;
-}
-export declare function resolveRuntimeValidationSpawnCommand(command: string[], platform?: NodeJS.Platform, shellCommand?: string): {
-    command: string;
-    args: string[];
-};
+import type { ExecutorRunResult } from "./executorResult.js";
 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;
@@ -23,12 +14,4 @@ export declare function runRuntimeValidationExecutor(bundle: ArtifactBundle, roo
     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

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { runCommand } from "./runtimeCommand.js";
 import { buildFileDisposition, isAuditExcludedStatus, } from "../extractors/disposition.js";
 import { buildGraphBundle, buildGraphBundleFromFs, } from "../extractors/graph.js";
 import { buildCriticalFlowManifest } from "../extractors/flows.js";
@@ -9,7 +9,6 @@ import { applyScopeToCoverage, fullAuditScope } from "./scope.js";
 import { buildFlowCoverage } from "./flowCoverage.js";
 import { buildRequeuePayload } from "./requeueCommand.js";
 import { buildRuntimeValidationTasks, discoverRuntimeValidationCommand, mergeRuntimeValidationReport, } from "./runtimeValidation.js";
-import { applyNarrative, buildAuditFindingsReport, buildAuditReportModel, renderAuditReportMarkdown, } from "../reporting/synthesis.js";
 import { buildChunkedAuditTasks, } from "./taskBuilder.js";
 import { buildAuditPlanMetrics, buildReviewPackets, sizeIndexFromManifest, } from "./reviewPackets.js";
 import { buildUnitManifest } from "./unitBuilder.js";
@@ -60,79 +59,6 @@ function appendSelectiveDeepeningTasks(params) {
         artifacts: ["audit_tasks.json", "audit_plan_metrics.json", "review_packets.json"],
     };
 }
-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, {
-            cwd,
-            env: process.env,
-            stdio: ["ignore", "pipe", "pipe"],
-        });
-        let stdout = "";
-        let stderr = "";
-        child.stdout.on("data", (chunk) => {
-            stdout += String(chunk);
-        });
-        child.stderr.on("data", (chunk) => {
-            stderr += String(chunk);
-        });
-        child.on("error", (error) => {
-            resolve({
-                status: "inconclusive",
-                summary: `Failed to execute ${displayCommand}: ${error.message}`,
-                evidence: [],
-            });
-        });
-        child.on("exit", (code) => {
-            const output = `${stdout}\n${stderr}`.trim();
-            const evidence = output.length > 0 ? output.split(/\r?\n/).slice(-10) : [];
-            resolve({
-                status: code === 0 ? "confirmed" : "not_confirmed",
-                summary: code === 0
-                    ? `Deterministic runtime command succeeded: ${displayCommand}`
-                    : `Deterministic runtime command failed with exit code ${code}: ${displayCommand}`,
-                evidence,
-            });
-        });
-    });
-}
-export function resolveRuntimeValidationSpawnCommand(command, platform = process.platform, shellCommand = process.env.ComSpec ?? "cmd.exe") {
-    const [executable, ...args] = command;
-    if (!executable) {
-        return { command: "", args: [] };
-    }
-    if (platform !== "win32") {
-        return { command: executable, args };
-    }
-    const packageManager = executable.replace(/\.(cmd|bat)$/i, "").toLowerCase();
-    if (["npm", "npx", "pnpm", "yarn"].includes(packageManager)) {
-        return {
-            command: shellCommand,
-            args: ["/d", "/s", "/c", command.map(quoteCmdArg).join(" ")],
-        };
-    }
-    return { command: executable, args };
-}
-function quoteCmdArg(value) {
-    if (/^[A-Za-z0-9_./:=+-]+$/.test(value)) {
-        return value;
-    }
-    return `"${value.replace(/(["^&|<>%])/g, "^$1")}"`;
-}
 export async function runIntakeExecutor(bundle, root) {
     const ignore = await loadIgnoreFile(root);
     const repoManifest = await buildRepoManifestFromFs({
@@ -476,89 +402,6 @@ export function runRuntimeValidationUpdateExecutor(bundle, updates) {
                 : ""),
     };
 }
-function buildBaseFindingsReport(bundle, results) {
-    return buildAuditFindingsReport(buildAuditReportModel({
-        results,
-        unitManifest: bundle.unit_manifest,
-        graphBundle: bundle.graph_bundle,
-        criticalFlows: bundle.critical_flows,
-        coverageMatrix: bundle.coverage_matrix,
-        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_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-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) {
     const summary = `Imported ${externalResults.results.length} normalized findings from ${externalResults.tool}.`;
     return {

package/dist/orchestrator/reviewPacketGraph.d.ts

@@ -0,0 +1,31 @@
+import type { AuditTask } from "../types.js";
+import type { ReviewPacketGraphEdge, ReviewPacketQuality } from "../types/reviewPlanning.js";
+import type { GraphBundle, GraphEdge } from "@audit-tools/shared";
+import { UnionFind } from "./unionFind.js";
+import { normalizeGraphPath } from "../extractors/graphPathUtils.js";
+export { normalizeGraphPath };
+/**
+ * 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 declare function collectGraphEdges(graphBundle?: GraphBundle): GraphEdge[];
+export declare function graphEdgeConfidence(edge: GraphEdge): number;
+export declare function isConcreteGraphEdge(edge: GraphEdge): boolean;
+export interface GraphDegreeIndex {
+    fanIn: Map<string, number>;
+    fanOut: Map<string, number>;
+}
+export declare function buildGraphDegreeIndex(edges: GraphEdge[]): GraphDegreeIndex;
+export declare function isPacketExpansionEdge(edge: GraphEdge, degreeIndex: GraphDegreeIndex): boolean;
+export declare function buildFileToGroupKeys(groups: Map<string, AuditTask[]>): Map<string, Set<string>>;
+export declare function unionFindFromGroups(groups: Map<string, AuditTask[]>, graphEdges: GraphEdge[]): UnionFind;
+export declare function buildPlanningGraphEdges(groups: Map<string, AuditTask[]>, graphEdges: GraphEdge[], graphBundle?: GraphBundle, lineIndex?: Record<string, number>, sizeIndex?: Record<string, number>, targetPacketTokens?: number): GraphEdge[];
+export declare function roundQuality(value: number): number;
+export declare function buildPacketGraphContext(filePaths: string[], graphEdges: GraphEdge[], graphBundle?: GraphBundle): {
+    keyEdges: ReviewPacketGraphEdge[];
+    boundaryFiles: string[];
+    entrypoints: string[];
+    quality: ReviewPacketQuality;
+};