auditor-lambda 0.3.41 → 0.5.0

package/dist/extractors/graphPythonImports.js

@@ -279,6 +279,42 @@ function addPythonImportEdge(edges, fromPath, target, kind, specifier) {
         reason: `Resolved Python import specifier '${specifier}'.`,
     }));
 }
+/**
+ * Resolve a single `import <spec>` module specifier to a repo file, or
+ * undefined. Shared with the tree-sitter Python analyzer so AST-extracted
+ * imports resolve to exactly the same targets as the regex floor.
+ */
+export function resolvePythonImportTarget(fromPath, specifier, pathLookup) {
+    if (!isPythonAbsoluteModuleSpecifier(specifier)) {
+        return undefined;
+    }
+    return resolvePythonModuleSpecifier(fromPath, specifier, pathLookup);
+}
+/**
+ * Resolve a `from <module> import <names>` statement to repo files. Mirrors the
+ * floor: prefer submodule files (`module.name`), else the module itself. Shared
+ * with the tree-sitter Python analyzer.
+ */
+export function resolvePythonFromImportTargets(fromPath, moduleSpecifier, importedNames, pathLookup) {
+    if (!isPythonModuleSpecifier(moduleSpecifier)) {
+        return [];
+    }
+    const submoduleTargets = importedNames
+        .filter((name) => name !== "*" && isPythonIdentifier(name))
+        .map((name) => appendPythonImportedSpecifier(moduleSpecifier, name))
+        .map((specifier) => ({
+        specifier,
+        target: resolvePythonModuleSpecifier(fromPath, specifier, pathLookup),
+    }))
+        .filter((item) => item.target !== undefined && item.target !== fromPath);
+    if (submoduleTargets.length > 0) {
+        return submoduleTargets;
+    }
+    const moduleTarget = resolvePythonModuleSpecifier(fromPath, moduleSpecifier, pathLookup);
+    return moduleTarget && moduleTarget !== fromPath
+        ? [{ specifier: moduleSpecifier, target: moduleTarget }]
+        : [];
+}
 export function extractPythonImportEdges(fromPath, content, pathLookup) {
     if (!isPythonSourcePath(fromPath)) {
         return [];

package/dist/extractors/pathPatterns.d.ts

@@ -8,6 +8,12 @@ export declare const EXTRACTOR_HEURISTIC_NOTE = "Heuristic path classification n
 export declare function normalizeExtractorPath(path: string): string;
 export declare function pathTokens(normalized: string): string[];
 export declare function isNodeModulesOrGit(normalized: string): boolean;
+/**
+ * `.tmp/` holds transient scratch and bundled tool copies (e.g. a vendored
+ * `.tmp/opentoken`). These are not the audited project's source — excluding
+ * them keeps the self-audit from auditing its own bundled dependencies.
+ */
+export declare function isTmpPath(normalized: string): boolean;
 export declare function isBuildOutput(normalized: string): boolean;
 export declare function isVendorPath(normalized: string): boolean;
 export declare function isBinaryArtifact(normalized: string): boolean;

package/dist/extractors/pathPatterns.js

@@ -156,6 +156,14 @@ function hasToken(normalized, values) {
 export function isNodeModulesOrGit(normalized) {
     return hasSegment(normalized, "node_modules") || hasSegment(normalized, ".git");
 }
+/**
+ * `.tmp/` holds transient scratch and bundled tool copies (e.g. a vendored
+ * `.tmp/opentoken`). These are not the audited project's source — excluding
+ * them keeps the self-audit from auditing its own bundled dependencies.
+ */
+export function isTmpPath(normalized) {
+    return hasSegment(normalized, ".tmp");
+}
 export function isBuildOutput(normalized) {
     return hasSegment(normalized, "dist") || hasSegment(normalized, "build");
 }

package/dist/io/artifacts.d.ts

@@ -2,12 +2,15 @@ import { cp, rm } from "node:fs/promises";
 import type { AuditResult, AuditTask, CoverageMatrix, RepoManifest, UnitManifest } from "../types.js";
 import type { AuditState } from "../types/auditState.js";
 import type { ArtifactMetadataManifest } from "../types/artifactMetadata.js";
-import type { FileDisposition, CriticalFlowManifest, GraphBundle, RiskRegister, SurfaceManifest } from "@audit-tools/shared";
+import type { AuditFindingsReport, FileDisposition, CriticalFlowManifest, GraphBundle, RiskRegister, SurfaceManifest } from "@audit-tools/shared";
+import type { SynthesisNarrativeRecord } from "../types/synthesisNarrative.js";
 import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
 import type { FlowCoverageManifest } from "../types/flowCoverage.js";
 import type { AuditPlanMetrics, ReviewPacket } from "../types/reviewPlanning.js";
 import type { RuntimeValidationReport, RuntimeValidationTaskManifest } from "../types/runtimeValidation.js";
 import type { DesignAssessment } from "../types/designAssessment.js";
+import type { AnalyzerCapabilityRecord } from "../types/analyzerCapability.js";
+import type { AuditScopeManifest } from "../types/auditScope.js";
 import type { ToolingManifest } from "../types/toolingManifest.js";
 type ArtifactPayloadMap = {
     repo_manifest: RepoManifest;
@@ -20,6 +23,8 @@ type ArtifactPayloadMap = {
     flow_coverage: FlowCoverageManifest;
     risk_register: RiskRegister;
     design_assessment: DesignAssessment;
+    analyzer_capability: AnalyzerCapabilityRecord;
+    scope: AuditScopeManifest;
     coverage_matrix: CoverageMatrix;
     runtime_validation_tasks: RuntimeValidationTaskManifest;
     runtime_validation_report: RuntimeValidationReport;
@@ -31,6 +36,8 @@ type ArtifactPayloadMap = {
     review_packets: ReviewPacket[];
     requeue_tasks: AuditTask[];
     audit_report: string;
+    audit_findings: AuditFindingsReport;
+    synthesis_narrative: SynthesisNarrativeRecord;
     audit_state: AuditState;
     artifact_metadata: ArtifactMetadataManifest;
     tooling_manifest: ToolingManifest;
@@ -59,6 +66,8 @@ export declare const ARTIFACT_DEFINITIONS: {
     readonly flow_coverage: ArtifactDefinition<"flow_coverage">;
     readonly risk_register: ArtifactDefinition<"risk_register">;
     readonly design_assessment: ArtifactDefinition<"design_assessment">;
+    readonly analyzer_capability: ArtifactDefinition<"analyzer_capability">;
+    readonly scope: ArtifactDefinition<"scope">;
     readonly coverage_matrix: ArtifactDefinition<"coverage_matrix">;
     readonly runtime_validation_tasks: ArtifactDefinition<"runtime_validation_tasks">;
     readonly runtime_validation_report: ArtifactDefinition<"runtime_validation_report">;
@@ -70,6 +79,8 @@ export declare const ARTIFACT_DEFINITIONS: {
     readonly review_packets: ArtifactDefinition<"review_packets">;
     readonly requeue_tasks: ArtifactDefinition<"requeue_tasks">;
     readonly audit_report: ArtifactDefinition<"audit_report">;
+    readonly audit_findings: ArtifactDefinition<"audit_findings">;
+    readonly synthesis_narrative: ArtifactDefinition<"synthesis_narrative">;
     readonly audit_state: ArtifactDefinition<"audit_state">;
     readonly artifact_metadata: ArtifactDefinition<"artifact_metadata">;
     readonly tooling_manifest: ArtifactDefinition<"tooling_manifest">;

package/dist/io/artifacts.js

@@ -37,6 +37,8 @@ export const ARTIFACT_DEFINITIONS = {
     flow_coverage: jsonArtifact("flow_coverage.json", "analysis"),
     risk_register: jsonArtifact("risk_register.json", "analysis"),
     design_assessment: jsonArtifact("design_assessment.json", "analysis"),
+    analyzer_capability: jsonArtifact("analyzer_capability.json", "analysis"),
+    scope: jsonArtifact("scope.json", "execution"),
     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"),
@@ -48,6 +50,8 @@ export const ARTIFACT_DEFINITIONS = {
     review_packets: jsonArtifact("review_packets.json", "execution"),
     requeue_tasks: jsonArtifact("requeue_tasks.json", "execution"),
     audit_report: textArtifact("audit-report.md", "reporting"),
+    audit_findings: jsonArtifact("audit-findings.json", "reporting"),
+    synthesis_narrative: jsonArtifact("synthesis-narrative.json", "reporting"),
     audit_state: jsonArtifact("audit_state.json", "supervisor"),
     artifact_metadata: jsonArtifact("artifact_metadata.json", "supervisor"),
     tooling_manifest: jsonArtifact("tooling_manifest.json", "supervisor"),
@@ -113,6 +117,14 @@ export async function promoteFinalAuditReport(params, options = {}) {
         warn(warning);
         return { promoted: false, cleaned: false, warning };
     }
+    // Promote the canonical machine contract alongside the human report. Missing
+    // (e.g. legacy bundle) or unreadable: best-effort, never blocks completion.
+    try {
+        await copy(join(params.artifactsDir, "audit-findings.json"), join(params.repoRoot, "audit-findings.json"), { force: true });
+    }
+    catch {
+        // audit-findings.json is optional output; absence must not fail promotion.
+    }
     try {
         await remove(params.artifactsDir, { recursive: true, force: true });
         return { promoted: true, cleaned: true };

package/dist/orchestrator/advance.d.ts

@@ -3,14 +3,34 @@ import type { AuditState } from "../types/auditState.js";
 import type { AuditResult } from "../types.js";
 import type { RuntimeValidationReport } from "../types/runtimeValidation.js";
 import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
+import { RunLogger } from "@audit-tools/shared";
+import type { AnalyzerSetting, SynthesisNarrative } from "@audit-tools/shared";
+import type { EdgeReasoningResults } from "./edgeReasoning.js";
 export interface AdvanceAuditOptions {
     root?: string;
     lineIndex?: Record<string, number>;
+    /** Path → size_bytes (from the repo manifest); drives byte-based packet token sizing. */
+    sizeIndex?: Record<string, number>;
     auditResults?: AuditResult[];
     runtimeValidationUpdates?: RuntimeValidationReport;
     externalAnalyzerResults?: ExternalAnalyzerResults;
+    /** Host/provider-supplied synthesis narrative; merged by synthesis_narrative_executor. */
+    narrativeResults?: SynthesisNarrative;
+    /** Per-analyzer resolution policy for the optional graph-enrichment pass. */
+    analyzers?: Record<string, AnalyzerSetting>;
+    /** Phase 4B gate (session-config `graph.llm_edge_reasoning`); default off. */
+    graphLlmEdgeReasoning?: boolean;
+    /** Phase 4B host-supplied reason rewrites for low-confidence graph edges. */
+    edgeReasoningResults?: EdgeReasoningResults;
+    /**
+     * Git ref for Phase 3 delta mode (the `--since` flag). When set and resolvable
+     * against a git repo, planning scopes coverage to the changed files and their
+     * graph neighbours; otherwise the run is a full audit.
+     */
+    since?: string;
     preferredExecutor?: string;
     opentoken?: boolean;
+    runLogger?: RunLogger;
 }
 export interface AdvanceAuditResult {
     audit_state: AuditState;

package/dist/orchestrator/advance.js

@@ -1,9 +1,12 @@
 import { decideNextStep, findObligation } from "./nextStep.js";
 import { deriveAuditState } from "./state.js";
 import { computeArtifactMetadata } from "./artifactMetadata.js";
-import { runIntakeExecutor, runStructureExecutor, runPlanningExecutor, runResultIngestionExecutor, runRuntimeValidationExecutor, runRuntimeValidationUpdateExecutor, runSynthesisExecutor, runDesignAssessmentExecutor, runDesignReviewAutoComplete, runExternalAnalyzerImportExecutor, } from "./internalExecutors.js";
+import { runIntakeExecutor, runStructureExecutor, runPlanningExecutor, runResultIngestionExecutor, runRuntimeValidationExecutor, runRuntimeValidationUpdateExecutor, runSynthesisExecutor, runSynthesisNarrativeExecutor, runDesignAssessmentExecutor, runDesignReviewAutoComplete, runExternalAnalyzerImportExecutor, } from "./internalExecutors.js";
 import { runAutoFixExecutor } from "./autoFixExecutor.js";
 import { runSyntaxResolutionExecutor } from "./syntaxResolutionExecutor.js";
+import { runGraphEnrichmentExecutor } from "./graphEnrichmentExecutor.js";
+import { resolveAuditScope } from "./scope.js";
+import { RunLogger } from "@audit-tools/shared";
 function cloneState(state) {
     return {
         ...state,
@@ -18,12 +21,19 @@ function formatExecutorFailure(selectedExecutor, selectedObligation, error) {
     });
 }
 export async function advanceAudit(bundle, options = {}) {
+    const log = options.runLogger ?? RunLogger.disabled();
     const decision = decideNextStep(bundle);
     const forcedExecutor = options.preferredExecutor ?? null;
     const selectedExecutor = forcedExecutor ?? decision.selected_executor;
     const selectedObligation = forcedExecutor
         ? `forced:${forcedExecutor}`
         : decision.selected_obligation;
+    log.event({
+        phase: "advance",
+        kind: "obligation",
+        obligation: selectedObligation ?? undefined,
+        note: decision.reason,
+    });
     if (!selectedExecutor) {
         const state = cloneState(decision.state);
         state.last_executor = bundle.audit_state?.last_executor ?? state.last_executor;
@@ -43,6 +53,14 @@ export async function advanceAudit(bundle, options = {}) {
         };
     }
     let run;
+    let plannedScope;
+    const executorStartedAt = Date.now();
+    log.event({
+        phase: "advance",
+        kind: "executor_start",
+        obligation: selectedObligation ?? undefined,
+        note: selectedExecutor,
+    });
     try {
         switch (selectedExecutor) {
             case "intake_executor":
@@ -53,6 +71,14 @@ export async function advanceAudit(bundle, options = {}) {
             case "structure_executor":
                 run = await runStructureExecutor(bundle, options.root);
                 break;
+            case "graph_enrichment_executor":
+                run = await runGraphEnrichmentExecutor(bundle, {
+                    root: options.root,
+                    analyzers: options.analyzers,
+                    llmEdgeReasoning: options.graphLlmEdgeReasoning,
+                    edgeReasoning: options.edgeReasoningResults,
+                });
+                break;
             case "design_assessment_executor":
                 run = runDesignAssessmentExecutor(bundle);
                 break;
@@ -62,7 +88,12 @@ export async function advanceAudit(bundle, options = {}) {
             case "planning_executor":
                 if (!options.root)
                     throw new Error("advanceAudit planning_executor requires root");
-                run = await runPlanningExecutor(bundle, options.root, options.lineIndex ?? {});
+                plannedScope = resolveAuditScope({
+                    root: options.root,
+                    since: options.since,
+                    bundle,
+                });
+                run = await runPlanningExecutor(bundle, options.root, options.lineIndex ?? {}, options.sizeIndex, plannedScope);
                 break;
             case "result_ingestion_executor":
                 run = runResultIngestionExecutor(bundle, options.auditResults ?? bundle.audit_results ?? []);
@@ -77,6 +108,9 @@ export async function advanceAudit(bundle, options = {}) {
             case "synthesis_executor":
                 run = runSynthesisExecutor(bundle, options.auditResults);
                 break;
+            case "synthesis_narrative_executor":
+                run = runSynthesisNarrativeExecutor(bundle, options.narrativeResults);
+                break;
             case "runtime_validation_update_executor":
                 if (!options.runtimeValidationUpdates)
                     throw new Error("advanceAudit runtime_validation_update_executor requires runtimeValidationUpdates");
@@ -117,6 +151,31 @@ export async function advanceAudit(bundle, options = {}) {
     catch (error) {
         throw formatExecutorFailure(selectedExecutor, selectedObligation, error);
     }
+    log.event({
+        phase: "advance",
+        kind: "executor_end",
+        obligation: selectedObligation ?? undefined,
+        note: selectedExecutor,
+        duration_ms: Date.now() - executorStartedAt,
+    });
+    if (plannedScope) {
+        log.event({
+            phase: "advance",
+            kind: "scope",
+            obligation: selectedObligation ?? undefined,
+            note: plannedScope.mode === "delta"
+                ? `delta since ${plannedScope.since}: ${plannedScope.seed_files.length} changed + ${plannedScope.expanded_files.length} neighbors; full audit advised before release`
+                : "full audit scope",
+        });
+    }
+    for (const artifact of run.artifacts_written) {
+        log.event({
+            phase: "advance",
+            kind: "artifact_write",
+            obligation: selectedObligation ?? undefined,
+            artifact,
+        });
+    }
     const metadata = computeArtifactMetadata(run.updated, bundle.artifact_metadata, [...run.artifacts_written, "tooling_manifest.json"]);
     const metadataBundle = {
         ...run.updated,

package/dist/orchestrator/dependencyMap.js

@@ -19,6 +19,15 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "runtime_validation_report.json",
         "audit-report.md",
     ],
+    // The optional graph-enrichment pass layers analyzer edges onto graph_bundle
+    // and records provenance in analyzer_capability.json. A re-built (structure)
+    // graph re-stales the marker so enrichment re-runs. No cycle: the enrichment
+    // executor writes graph_bundle AND the marker in one advanceAudit call, and
+    // computeArtifactMetadata is dependency-first, so the marker records the
+    // post-enrichment graph_bundle revision (mirrors audit-findings → narrative).
+    "graph_bundle.json": [
+        "analyzer_capability.json",
+    ],
     "file_disposition.json": [
         "unit_manifest.json",
         "surface_manifest.json",
@@ -91,6 +100,17 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "runtime_validation_report.json",
         "audit-report.md",
     ],
+    // Phase 3 delta scope. scope.json is produced by the planning executor (full
+    // or delta) and gates coverage: in delta mode it decides which coverage
+    // entries are (re)queued vs. inherited-complete/excluded. A changed scope
+    // (different `--since`/seed set → new content hash) re-stales coverage so the
+    // plan rebuilds. No cycle: planning writes scope.json AND coverage_matrix.json
+    // in one advanceAudit call, and computeArtifactMetadata is dependency-first,
+    // so coverage records the post-write scope revision (mirrors graph_bundle →
+    // analyzer_capability and audit-findings → narrative).
+    "scope.json": [
+        "coverage_matrix.json",
+    ],
     "coverage_matrix.json": [
         "flow_coverage.json",
         "audit_plan_metrics.json",
@@ -115,4 +135,11 @@ export const ARTIFACT_DEPENDENCY_MAP = {
     "runtime_validation_report.json": [
         "audit-report.md",
     ],
+    // The canonical machine contract is co-produced with audit-report.md by the
+    // synthesis executor. The optional narrative pass tracks its revision: a fresh
+    // (re-synthesized) audit-findings.json re-stales the narrative marker so the
+    // themes/executive-summary/top-risks regenerate. See spec/dependency-map.md.
+    "audit-findings.json": [
+        "synthesis-narrative.json",
+    ],
 };

package/dist/orchestrator/edgeReasoning.d.ts

@@ -0,0 +1,39 @@
+import type { GraphBundle, GraphEdge } from "@audit-tools/shared";
+export declare const DEFAULT_EDGE_CONFIDENCE_FLOOR = 0.65;
+/** Bound the candidate set so one pathological repo cannot balloon the call. */
+export declare const MAX_REASONED_EDGES = 200;
+/** One host-supplied reason rewrite, matched to an edge by (from, to, kind). */
+export interface EdgeReasonRewrite {
+    from: string;
+    to: string;
+    /** Optional; when omitted the rewrite matches any candidate with from+to. */
+    kind?: string;
+    reason: string;
+}
+export interface EdgeReasoningResults {
+    rewrites: EdgeReasonRewrite[];
+}
+export interface EdgeReasoningOptions {
+    /** Edges strictly below this confidence are candidates (default 0.65). */
+    confidenceFloor?: number;
+}
+export interface EdgeReasoningSummary {
+    rewritten: number;
+    candidates: number;
+}
+/**
+ * Collect the low-confidence edges (the actual edge objects, so the caller can
+ * mutate `reason` in place) in a deterministic order. Routes are excluded — they
+ * carry no `reason`/`confidence`.
+ */
+export declare function collectLowConfidenceEdges(bundle: GraphBundle, floor?: number): GraphEdge[];
+/** Stable content hash of the candidate edge set, for host-side call caching. */
+export declare function edgeReasoningContentHash(candidates: GraphEdge[]): string;
+/** The single bounded prompt a host runs to produce {@link EdgeReasoningResults}. */
+export declare function buildEdgeReasoningPrompt(candidates: GraphEdge[]): string;
+/**
+ * Apply host-supplied reason rewrites to `bundle` (mutated in place). Only edges
+ * below the confidence floor are eligible; a rewrite that matches no eligible
+ * edge is ignored. Returns a summary; the edge set itself is invariant.
+ */
+export declare function applyEdgeReasoning(bundle: GraphBundle, results: EdgeReasoningResults | undefined, options?: EdgeReasoningOptions): EdgeReasoningSummary;

package/dist/orchestrator/edgeReasoning.js

@@ -0,0 +1,125 @@
+import { createHash } from "node:crypto";
+/**
+ * Phase 4B — optional, bounded edge-reasoning pass.
+ *
+ * A deterministic transform that may only rewrite the human-readable `reason`
+ * of existing low-confidence graph edges. It never adds, removes, re-targets, or
+ * re-weights an edge: the `(from, to, kind, confidence, direction)` identity of
+ * every edge is preserved exactly. Rewrites are host/provider-supplied (the same
+ * conversation-first pattern as the Phase 6 synthesis narrative) — no in-process
+ * LLM call. No rewrites (or the config flag off) → no-op, leaving the
+ * deterministic graph byte-identical. This is part of the
+ * `graph_enrichment_current` obligation.
+ *
+ * The pass is bounded to edges below a confidence floor (default 0.65) because
+ * those are exactly the heuristic edges whose terse machine reason benefits from
+ * a clearer explanation; high-confidence compiler/import edges are left alone.
+ * {@link buildEdgeReasoningPrompt} and {@link edgeReasoningContentHash} let a
+ * host produce and cache that single rewriting call by edge-set content hash.
+ */
+const EDGE_REASONING_VERSION = 1;
+export const DEFAULT_EDGE_CONFIDENCE_FLOOR = 0.65;
+/** Bound the candidate set so one pathological repo cannot balloon the call. */
+export const MAX_REASONED_EDGES = 200;
+function confidenceOf(edge) {
+    return typeof edge.confidence === "number" && Number.isFinite(edge.confidence)
+        ? edge.confidence
+        : 0;
+}
+function edgeSignature(edge) {
+    return `${edge.from}\0${edge.to}\0${edge.kind ?? ""}`;
+}
+/**
+ * Collect the low-confidence edges (the actual edge objects, so the caller can
+ * mutate `reason` in place) in a deterministic order. Routes are excluded — they
+ * carry no `reason`/`confidence`.
+ */
+export function collectLowConfidenceEdges(bundle, floor = DEFAULT_EDGE_CONFIDENCE_FLOOR) {
+    const candidates = [];
+    for (const bucket of [
+        bundle.graphs.imports,
+        bundle.graphs.calls,
+        bundle.graphs.references,
+    ]) {
+        for (const edge of bucket ?? []) {
+            if (confidenceOf(edge) < floor) {
+                candidates.push(edge);
+            }
+        }
+    }
+    return candidates
+        .sort((a, b) => edgeSignature(a).localeCompare(edgeSignature(b)))
+        .slice(0, MAX_REASONED_EDGES);
+}
+/** Stable content hash of the candidate edge set, for host-side call caching. */
+export function edgeReasoningContentHash(candidates) {
+    const basis = JSON.stringify({
+        version: EDGE_REASONING_VERSION,
+        edges: candidates.map((edge) => ({
+            from: edge.from,
+            to: edge.to,
+            kind: edge.kind ?? "",
+            confidence: confidenceOf(edge),
+            reason: edge.reason ?? "",
+        })),
+    });
+    return createHash("sha256").update(basis).digest("hex");
+}
+/** The single bounded prompt a host runs to produce {@link EdgeReasoningResults}. */
+export function buildEdgeReasoningPrompt(candidates) {
+    const lines = candidates.map((edge) => `- from: ${edge.from} | to: ${edge.to} | kind: ${edge.kind ?? "?"} | confidence: ${confidenceOf(edge).toFixed(2)} | current: ${edge.reason ?? "(none)"}`);
+    return [
+        "You are improving the human-readable 'reason' for low-confidence edges in a code dependency graph.",
+        "Each edge links a source file to a target file by a relationship 'kind'.",
+        "For each edge you can improve, write one clear, specific sentence explaining why that relationship plausibly holds.",
+        "Do NOT invent new edges, drop edges, or change which files are linked — only rewrite the reason text.",
+        "Omit any edge whose reason you cannot improve.",
+        "",
+        "Edges:",
+        ...lines,
+        "",
+        'Respond with JSON only: {"rewrites":[{"from":"...","to":"...","kind":"...","reason":"..."}]}',
+    ].join("\n");
+}
+/**
+ * Apply host-supplied reason rewrites to `bundle` (mutated in place). Only edges
+ * below the confidence floor are eligible; a rewrite that matches no eligible
+ * edge is ignored. Returns a summary; the edge set itself is invariant.
+ */
+export function applyEdgeReasoning(bundle, results, options = {}) {
+    const floor = options.confidenceFloor ?? DEFAULT_EDGE_CONFIDENCE_FLOOR;
+    const candidates = collectLowConfidenceEdges(bundle, floor);
+    if (!results || !Array.isArray(results.rewrites) || candidates.length === 0) {
+        return { rewritten: 0, candidates: candidates.length };
+    }
+    const bySignature = new Map();
+    const byEndpoints = new Map();
+    for (const edge of candidates) {
+        bySignature.set(edgeSignature(edge), edge);
+        const endpoints = `${edge.from}\0${edge.to}`;
+        if (!byEndpoints.has(endpoints)) {
+            byEndpoints.set(endpoints, edge);
+        }
+    }
+    let rewritten = 0;
+    const seen = new Set();
+    for (const rewrite of results.rewrites) {
+        if (!rewrite ||
+            typeof rewrite.from !== "string" ||
+            typeof rewrite.to !== "string" ||
+            typeof rewrite.reason !== "string" ||
+            rewrite.reason.trim().length === 0) {
+            continue;
+        }
+        const edge = rewrite.kind !== undefined
+            ? bySignature.get(`${rewrite.from}\0${rewrite.to}\0${rewrite.kind}`)
+            : byEndpoints.get(`${rewrite.from}\0${rewrite.to}`);
+        if (!edge || seen.has(edge)) {
+            continue;
+        }
+        edge.reason = rewrite.reason.trim();
+        seen.add(edge);
+        rewritten += 1;
+    }
+    return { rewritten, candidates: candidates.length };
+}

package/dist/orchestrator/executors.js

@@ -9,6 +9,11 @@ export const EXECUTOR_REGISTRY = [
         obligation_ids: ["structure_artifacts"],
         description: "Build structure artifacts such as units, surfaces, graphs, flows, and risk.",
     },
+    {
+        id: "graph_enrichment_executor",
+        obligation_ids: ["graph_enrichment_current"],
+        description: "Layer optional language-analyzer edges onto the deterministic graph (regex floor preserved); record analyzer provenance.",
+    },
     {
         id: "design_assessment_executor",
         obligation_ids: ["design_assessment_current"],
@@ -42,7 +47,12 @@ export const EXECUTOR_REGISTRY = [
     {
         id: "synthesis_executor",
         obligation_ids: ["synthesis_current"],
-        description: "Render the final deterministic Markdown audit report.",
+        description: "Emit the canonical audit-findings.json and render the deterministic Markdown audit report.",
+    },
+    {
+        id: "synthesis_narrative_executor",
+        obligation_ids: ["synthesis_narrative_current"],
+        description: "Resolve the optional synthesis narrative (themes, executive summary, top risks); omit deterministically without a provider.",
     },
     {
         id: "external_analyzer_import_executor",

package/dist/orchestrator/graphEnrichmentExecutor.d.ts

@@ -0,0 +1,29 @@
+import type { ArtifactBundle } from "../io/artifacts.js";
+import type { ExecutorRunResult } from "./internalExecutors.js";
+import type { AnalyzerSetting } from "@audit-tools/shared";
+import type { LanguageAnalyzer } from "../extractors/analyzers/types.js";
+import { type EdgeReasoningResults } from "./edgeReasoning.js";
+export interface GraphEnrichmentOptions {
+    root?: string;
+    analyzers?: Record<string, AnalyzerSetting>;
+    /** Injectable for tests; defaults to the global registry. */
+    registry?: LanguageAnalyzer[];
+    /** Injectable analyzer-cache root; defaults to ~/.audit-tools/analyzer-cache. */
+    cacheRoot?: string;
+    /**
+     * Phase 4B: gate for the optional edge-reasoning pass (mirrors
+     * session-config `graph.llm_edge_reasoning`; default off).
+     */
+    llmEdgeReasoning?: boolean;
+    /** Phase 4B: host-supplied reason rewrites for low-confidence edges. */
+    edgeReasoning?: EdgeReasoningResults;
+}
+/**
+ * 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 declare function runGraphEnrichmentExecutor(bundle: ArtifactBundle, options?: GraphEnrichmentOptions): Promise<ExecutorRunResult>;