auditor-lambda 0.3.41 → 0.6.0

package/dist/reporting/synthesis.d.ts

@@ -1,9 +1,26 @@
 import type { AuditResult, CoverageMatrix, Finding, UnitManifest } from "../types.js";
+import type { AuditScopeManifest } from "../types/auditScope.js";
 import type { DesignAssessment } from "../types/designAssessment.js";
 import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
-import type { CriticalFlowManifest, GraphBundle } from "@audit-tools/shared";
+import type { AuditFindingsReport, CriticalFlowManifest, Finding as SharedFinding, FindingTheme, GraphBundle, SynthesisNarrative } from "@audit-tools/shared";
 import type { RuntimeValidationReport } from "../types/runtimeValidation.js";
 import { type WorkBlock } from "./workBlocks.js";
+/** Contract version stamped onto the canonical `audit-findings.json`. */
+export declare const AUDIT_FINDINGS_CONTRACT_VERSION = "audit-tools/audit-findings/v1";
+/**
+ * Anything renderable as the deterministic audit report. Both `AuditReportModel`
+ * (no narrative) and the canonical `AuditFindingsReport` (optionally carrying
+ * themes/executive_summary/top_risks) satisfy this shape, so the same renderer
+ * produces the base report and the narrative-enriched report.
+ */
+export interface RenderableAuditReport {
+    summary: AuditReportSummary;
+    findings: SharedFinding[];
+    work_blocks: WorkBlock[];
+    themes?: FindingTheme[];
+    executive_summary?: string;
+    top_risks?: string[];
+}
 export interface AuditReportSummary {
     finding_count: number;
     work_block_count: number;
@@ -27,4 +44,22 @@ export declare function buildAuditReportModel(params: {
     externalAnalyzerResults?: ExternalAnalyzerResults;
     designAssessment?: DesignAssessment;
 }): AuditReportModel;
-export declare function renderAuditReportMarkdown(model: AuditReportModel): string;
+/**
+ * Wrap the deterministic report model in the canonical `audit-findings.json`
+ * contract — the machine hand-off consumed by the remediator. Narrative fields
+ * are absent here; they are layered on later by {@link applyNarrative}.
+ */
+export declare function buildAuditFindingsReport(model: AuditReportModel): AuditFindingsReport;
+/**
+ * Merge an LLM synthesis narrative into the canonical findings report: keep only
+ * themes whose `finding_ids` reference real findings, tag each covered finding
+ * with its (first-claiming) `theme_id`, and attach the executive summary / top
+ * risks. Deterministic and idempotent — the same narrative yields the same
+ * report.
+ */
+export declare function applyNarrative(report: AuditFindingsReport, narrative: SynthesisNarrative): AuditFindingsReport;
+export interface RenderAuditReportOptions {
+    /** Scope manifest for the run; when delta, the report header reports it honestly. */
+    scope?: AuditScopeManifest;
+}
+export declare function renderAuditReportMarkdown(report: RenderableAuditReport, options?: RenderAuditReportOptions): string;

package/dist/reporting/synthesis.js

@@ -1,6 +1,8 @@
 import { AUDITOR_REPORT_MARKER } from "@audit-tools/shared";
 import { buildWorkBlocks } from "./workBlocks.js";
 import { mergeFindings } from "./mergeFindings.js";
+/** Contract version stamped onto the canonical `audit-findings.json`. */
+export const AUDIT_FINDINGS_CONTRACT_VERSION = "audit-tools/audit-findings/v1";
 function countBy(items, selectKey) {
     const breakdown = {};
     for (const item of items) {
@@ -54,27 +56,92 @@ export function buildAuditReportModel(params) {
         work_blocks: workBlocks,
     };
 }
-export function renderAuditReportMarkdown(model) {
+/**
+ * Wrap the deterministic report model in the canonical `audit-findings.json`
+ * contract — the machine hand-off consumed by the remediator. Narrative fields
+ * are absent here; they are layered on later by {@link applyNarrative}.
+ */
+export function buildAuditFindingsReport(model) {
+    return {
+        contract_version: AUDIT_FINDINGS_CONTRACT_VERSION,
+        summary: { ...model.summary },
+        findings: model.findings,
+        work_blocks: model.work_blocks,
+    };
+}
+/**
+ * Merge an LLM synthesis narrative into the canonical findings report: keep only
+ * themes whose `finding_ids` reference real findings, tag each covered finding
+ * with its (first-claiming) `theme_id`, and attach the executive summary / top
+ * risks. Deterministic and idempotent — the same narrative yields the same
+ * report.
+ */
+export function applyNarrative(report, narrative) {
+    const validFindingIds = new Set(report.findings.map((finding) => finding.id));
+    const themeByFinding = new Map();
+    const themes = [];
+    for (const theme of narrative.themes ?? []) {
+        const findingIds = [
+            ...new Set((theme.finding_ids ?? []).filter((id) => validFindingIds.has(id))),
+        ];
+        themes.push({
+            theme_id: theme.theme_id,
+            title: theme.title,
+            root_cause: theme.root_cause,
+            finding_ids: findingIds,
+            suggested_fix_pattern: theme.suggested_fix_pattern,
+        });
+        for (const id of findingIds) {
+            if (!themeByFinding.has(id)) {
+                themeByFinding.set(id, theme.theme_id);
+            }
+        }
+    }
+    const findings = report.findings.map((finding) => themeByFinding.has(finding.id)
+        ? { ...finding, theme_id: themeByFinding.get(finding.id) }
+        : finding);
+    return {
+        ...report,
+        findings,
+        themes,
+        executive_summary: narrative.executive_summary,
+        top_risks: narrative.top_risks,
+    };
+}
+export function renderAuditReportMarkdown(report, options = {}) {
     const lines = [
         AUDITOR_REPORT_MARKER,
         "# Audit Report",
         "",
-        "## Summary",
-        "",
-        `- Findings: ${model.summary.finding_count}`,
-        `- Work blocks: ${model.summary.work_block_count}`,
-        `- Severity breakdown: ${formatSeverityList(model.summary.severity_breakdown)}`,
-        `- Fully audited files: ${model.summary.audited_file_count}`,
-        `- Excluded non-auditable files: ${model.summary.excluded_file_count}`,
-        "",
-        "## Work Blocks",
-        "",
     ];
-    if (model.work_blocks.length === 0) {
+    if (report.executive_summary && report.executive_summary.trim().length > 0) {
+        lines.push("## Executive Summary", "", report.executive_summary.trim(), "");
+    }
+    lines.push("## Summary", "", `- Findings: ${report.summary.finding_count}`, `- Work blocks: ${report.summary.work_block_count}`, `- Severity breakdown: ${formatSeverityList(report.summary.severity_breakdown)}`, `- Fully audited files: ${report.summary.audited_file_count}`, `- Excluded non-auditable files: ${report.summary.excluded_file_count}`, "");
+    if (report.top_risks && report.top_risks.length > 0) {
+        lines.push("## Top Risks", "");
+        for (const risk of report.top_risks) {
+            lines.push(`- ${risk}`);
+        }
+        lines.push("");
+    }
+    if (report.themes && report.themes.length > 0) {
+        lines.push("## Themes", "");
+        for (const theme of report.themes) {
+            lines.push(`### ${theme.theme_id} — ${theme.title}`);
+            lines.push("");
+            lines.push(`- Root cause: ${theme.root_cause}`);
+            lines.push(`- Findings: ${theme.finding_ids.length > 0 ? theme.finding_ids.join(", ") : "none"}`);
+            lines.push(`- Suggested fix pattern: ${theme.suggested_fix_pattern}`);
+            lines.push("");
+        }
+    }
+    lines.push("## Work Blocks", "");
+    if (report.work_blocks.length === 0) {
         lines.push("No remediation work blocks were generated.", "");
     }
     else {
-        for (const block of model.work_blocks) {
+        for (const block of report.work_blocks) {
             lines.push(`### ${block.id}`);
             lines.push("");
             lines.push(`- Max severity: ${block.max_severity}`);
@@ -87,16 +154,19 @@ export function renderAuditReportMarkdown(model) {
         }
     }
     lines.push("## Findings", "");
-    if (model.findings.length === 0) {
+    if (report.findings.length === 0) {
         lines.push("No findings were recorded.", "");
     }
     else {
-        for (const finding of model.findings) {
+        for (const finding of report.findings) {
             lines.push(`### ${finding.id} — ${finding.title}`);
             lines.push("");
             lines.push(`- Severity: ${finding.severity}`);
             lines.push(`- Confidence: ${finding.confidence}`);
             lines.push(`- Lens: ${finding.lens}`);
+            if (finding.theme_id) {
+                lines.push(`- Theme: ${finding.theme_id}`);
+            }
             lines.push(`- Files: ${finding.affected_files.map((file) => file.path).join(", ")}`);
             lines.push(`- Summary: ${finding.summary}`);
             if (finding.evidence && finding.evidence.length > 0) {
@@ -109,7 +179,16 @@ export function renderAuditReportMarkdown(model) {
         }
     }
     lines.push("## Scope and Coverage", "");
-    lines.push("This report is deterministic output from the completed audit. Non-auditable files were excluded from scope before task generation.");
+    const scope = options.scope;
+    if (scope && scope.mode === "delta") {
+        lines.push(`**Delta audit since \`${scope.since}\`.** This run audited ${scope.seed_files.length} changed file(s) and ${scope.expanded_files.length} graph neighbour(s); all other auditable files were left out of scope (inherited from a prior audit where complete, otherwise excluded from this run). **A full audit is advised before release.**`);
+        if (scope.dropped_note) {
+            lines.push("", scope.dropped_note);
+        }
+    }
+    else {
+        lines.push("This report is deterministic output from the completed audit. Non-auditable files were excluded from scope before task generation.");
+    }
     lines.push("");
     return lines.join("\n");
 }

package/dist/reporting/synthesisNarrativePrompt.d.ts

@@ -0,0 +1,7 @@
+import type { AuditFindingsReport } from "@audit-tools/shared";
+/**
+ * Prompt for the optional synthesis-narrative pass. The host groups the
+ * already-finalized deterministic findings into root-cause themes and writes a
+ * `SynthesisNarrative` JSON document — it does not re-audit or invent findings.
+ */
+export declare function renderSynthesisNarrativePrompt(report: AuditFindingsReport): string;

package/dist/reporting/synthesisNarrativePrompt.js

@@ -0,0 +1,60 @@
+const MAX_RENDERED_FINDINGS = 120;
+function summarizeFinding(finding) {
+    const files = finding.affected_files
+        .map((file) => file.path)
+        .slice(0, 4)
+        .join(", ");
+    return `- ${finding.id} [${finding.severity}/${finding.lens}] ${finding.title} — ${finding.summary}${files ? ` (files: ${files})` : ""}`;
+}
+/**
+ * Prompt for the optional synthesis-narrative pass. The host groups the
+ * already-finalized deterministic findings into root-cause themes and writes a
+ * `SynthesisNarrative` JSON document — it does not re-audit or invent findings.
+ */
+export function renderSynthesisNarrativePrompt(report) {
+    const findings = report.findings;
+    const rendered = findings.slice(0, MAX_RENDERED_FINDINGS).map(summarizeFinding);
+    const overflowNote = findings.length > MAX_RENDERED_FINDINGS
+        ? [`  ... and ${findings.length - MAX_RENDERED_FINDINGS} more findings (see audit-findings.json).`]
+        : [];
+    return [
+        "# Synthesis narrative",
+        "",
+        "The deterministic audit is complete. Your job is to add an interpretive narrative on top of the finalized findings — group them into a small number of root-cause themes, write a short executive summary, and list the top risks.",
+        "",
+        "Do not re-audit the code, change severities, or invent new findings. Use only the findings below; reference them by their exact `id`.",
+        "",
+        "## Summary",
+        "",
+        `- Findings: ${report.summary.finding_count}`,
+        `- Work blocks: ${report.summary.work_block_count}`,
+        "",
+        "## Findings",
+        "",
+        ...(rendered.length > 0 ? rendered : ["- (no findings were recorded)"]),
+        ...overflowNote,
+        "",
+        "## Output format",
+        "",
+        "Write a single JSON object conforming to:",
+        "",
+        "```json",
+        "{",
+        '  "themes": [',
+        "    {",
+        '      "theme_id": "T-001",',
+        '      "title": "short root-cause title",',
+        '      "root_cause": "what underlying cause ties these findings together",',
+        '      "finding_ids": ["<finding id>", "..."],',
+        '      "suggested_fix_pattern": "the shared remediation approach for this theme"',
+        "    }",
+        "  ],",
+        '  "executive_summary": "2-4 sentence overview of the audit outcome",',
+        '  "top_risks": ["highest-impact risk", "..."]',
+        "}",
+        "```",
+        "",
+        "Prefer a handful of substantive themes over many thin ones. Every `finding_ids` entry must be an id listed above; unknown ids are dropped. A finding may belong to at most one theme.",
+        "",
+    ].join("\n");
+}

package/dist/reporting/workBlocks.d.ts

@@ -1,14 +1,6 @@
 import type { Finding, UnitManifest } from "../types.js";
-import type { CriticalFlowManifest, GraphBundle } from "@audit-tools/shared";
-export interface WorkBlock {
-    id: string;
-    finding_ids: string[];
-    unit_ids: string[];
-    owned_files: string[];
-    max_severity: Finding["severity"];
-    rationale: string;
-    depends_on: string[];
-}
+import type { CriticalFlowManifest, GraphBundle, WorkBlock } from "@audit-tools/shared";
+export type { WorkBlock } from "@audit-tools/shared";
 export declare function buildWorkBlocks(params: {
     findings: Finding[];
     unitManifest?: UnitManifest;

package/dist/supervisor/operatorHandoff.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactBundle } from "../io/artifacts.js";
+import { type ArtifactBundle } from "../io/artifacts.js";
 import type { AuditState, AuditTopLevelStatus } from "../types/auditState.js";
 export interface AuditCodeHandoffInput {
     flag: "--results" | "--batch-results" | "--updates" | "--external-analyzer-results";

package/dist/supervisor/operatorHandoff.js

@@ -1,6 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { writeJsonFile } from "@audit-tools/shared";
+import { AUDIT_REPORT_FILENAME } from "../io/artifacts.js";
 import { LOCAL_SUBPROCESS_PROVIDER_NAME } from "../providers/constants.js";
 export const CONFIG_ERROR_BLOCKER_PREFIX = "config-error:";
 const INCOMING_DIRNAME = "incoming";
@@ -11,8 +12,6 @@ const RUN_LEDGER_FILENAME = "run-ledger.json";
 const CURRENT_TASK_FILENAME = "current-task.json";
 const CURRENT_PROMPT_FILENAME = "current-prompt.md";
 const CURRENT_TASKS_FILENAME = "current-tasks.json";
-const CURRENT_SINGLE_TASK_FILENAME = "current-single-task.json";
-const CURRENT_SINGLE_TASK_PROMPT_FILENAME = "current-single-task-prompt.md";
 const AUDIT_TASKS_FILENAME = "audit_tasks.json";
 const RUNTIME_VALIDATION_TASKS_FILENAME = "runtime_validation_tasks.json";
 const BLOCKED_STATUS = "blocked";
@@ -123,6 +122,26 @@ function buildInteractiveProviderHint(status, providerName, sessionConfigPath, i
     const providerLabel = providerName ?? LOCAL_SUBPROCESS_PROVIDER_NAME;
     return `Provider: ${providerLabel}. This is a deterministic semantic-review handoff, not a failed audit. Use host subagents when the active toolset provides them; otherwise use the single-task fallback and stop after the worker command. For automatic LLM review, configure an interactive provider in ${sessionConfigPath}; that is only needed for backend-launched review.`;
 }
+// Single source for which artifact paths render in the markdown handoff and how
+// absent ones read. renderMarkdown and file_map both source paths from the
+// artifact path model (AuditCodeHandoffArtifactPaths), so adding or renaming a
+// handoff artifact is one edit here instead of coordinated edits across sites.
+const ARTIFACT_PATH_RENDER_FIELDS = [
+    { label: "operator handoff json", key: "operator_handoff_json" },
+    { label: "operator handoff markdown", key: "operator_handoff_markdown" },
+    { label: "incoming dir", key: "incoming_dir" },
+    { label: "session config", key: "session_config" },
+    { label: "run ledger", key: "run_ledger" },
+    { label: "current task", key: "current_task", fallback: "not available" },
+    { label: "current prompt", key: "current_prompt", fallback: "not available" },
+    { label: "current tasks", key: "current_tasks", fallback: "not available" },
+    { label: "audit tasks", key: "audit_tasks", fallback: "not available yet" },
+    {
+        label: "runtime validation tasks",
+        key: "runtime_validation_tasks",
+        fallback: "not available yet",
+    },
+];
 function renderMarkdown(handoff) {
     const lines = [
         "# audit-code operator handoff",
@@ -145,16 +164,10 @@ function renderMarkdown(handoff) {
         }
     }
     lines.push("", "Useful artifact paths:");
-    lines.push(`- operator handoff json: ${handoff.artifact_paths.operator_handoff_json}`);
-    lines.push(`- operator handoff markdown: ${handoff.artifact_paths.operator_handoff_markdown}`);
-    lines.push(`- incoming dir: ${handoff.artifact_paths.incoming_dir}`);
-    lines.push(`- session config: ${handoff.artifact_paths.session_config}`);
-    lines.push(`- run ledger: ${handoff.artifact_paths.run_ledger}`);
-    lines.push(`- current task: ${handoff.artifact_paths.current_task ?? "not available"}`);
-    lines.push(`- current prompt: ${handoff.artifact_paths.current_prompt ?? "not available"}`);
-    lines.push(`- current tasks: ${handoff.artifact_paths.current_tasks ?? "not available"}`);
-    lines.push(`- audit tasks: ${handoff.artifact_paths.audit_tasks ?? "not available yet"}`);
-    lines.push(`- runtime validation tasks: ${handoff.artifact_paths.runtime_validation_tasks ?? "not available yet"}`);
+    for (const field of ARTIFACT_PATH_RENDER_FIELDS) {
+        const value = handoff.artifact_paths[field.key];
+        lines.push(`- ${field.label}: ${value ?? field.fallback ?? "not available"}`);
+    }
     if (handoff.suggested_inputs.length > 0) {
         lines.push("", "Suggested evidence inputs:");
         for (const item of handoff.suggested_inputs) {
@@ -238,11 +251,8 @@ export function buildAuditCodeHandoff(params) {
         handoff.file_map = {
             current_task: artifactPaths.current_task,
             current_prompt: artifactPaths.current_prompt,
-            single_task: join(params.artifactsDir, "dispatch", CURRENT_SINGLE_TASK_FILENAME),
-            single_task_prompt: join(params.artifactsDir, "dispatch", CURRENT_SINGLE_TASK_PROMPT_FILENAME),
-            dispatch_plan: join(params.artifactsDir, "runs", params.activeReviewRun.run_id, "dispatch-plan.json"),
             audit_results: params.activeReviewRun.audit_results_path,
-            final_report: join(params.root, "audit-report.md"),
+            final_report: join(params.root, AUDIT_REPORT_FILENAME),
         };
     }
     return handoff;

package/dist/supervisor/sessionConfig.d.ts

@@ -1,4 +1,11 @@
-import { type SessionConfig } from "@audit-tools/shared";
+import { type AnalyzerSetting, type SessionConfig } from "@audit-tools/shared";
 export declare function getSessionConfigPath(artifactsDir: string): string;
 export declare function readSessionConfigFile(artifactsDir: string): Promise<unknown | undefined>;
 export declare function loadSessionConfig(artifactsDir: string): Promise<SessionConfig>;
+/**
+ * Merge per-analyzer resolution decisions into `session-config.json`,
+ * preserving any unknown fields, validating, and persisting the result. Used by
+ * the conversation-first `analyzer_install` step to durably record the host's
+ * `{ephemeral|permanent|skip}` choices under `analyzers.<id>`.
+ */
+export declare function persistAnalyzerSettings(artifactsDir: string, settings: Record<string, AnalyzerSetting>): Promise<SessionConfig>;

package/dist/supervisor/sessionConfig.js

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { readOptionalJsonFile, writeJsonFile, formatValidationIssues, } from "@audit-tools/shared";
+import { isRecord, readOptionalJsonFile, writeJsonFile, formatValidationIssues, } from "@audit-tools/shared";
 import { validateSessionConfig } from "../validation/sessionConfig.js";
 const SESSION_CONFIG_FILENAME = "session-config.json";
 const DEFAULT_SESSION_CONFIG = { provider: "local-subprocess" };
@@ -25,3 +25,24 @@ export async function loadSessionConfig(artifactsDir) {
     }
     return rawConfig;
 }
+/**
+ * Merge per-analyzer resolution decisions into `session-config.json`,
+ * preserving any unknown fields, validating, and persisting the result. Used by
+ * the conversation-first `analyzer_install` step to durably record the host's
+ * `{ephemeral|permanent|skip}` choices under `analyzers.<id>`.
+ */
+export async function persistAnalyzerSettings(artifactsDir, settings) {
+    const configPath = getSessionConfigPath(artifactsDir);
+    const raw = (await readOptionalJsonFile(configPath)) ?? {
+        ...DEFAULT_SESSION_CONFIG,
+    };
+    const base = isRecord(raw) ? raw : { ...DEFAULT_SESSION_CONFIG };
+    const current = isRecord(base.analyzers) ? base.analyzers : {};
+    const merged = { ...base, analyzers: { ...current, ...settings } };
+    const issues = validateSessionConfig(merged);
+    if (issues.length > 0) {
+        throw new Error(formatConfigValidationIssues(configPath, issues));
+    }
+    await writeJsonFile(configPath, merged);
+    return merged;
+}

package/dist/types/analyzerCapability.d.ts

@@ -0,0 +1,16 @@
+import type { AnalyzerSetting } from "@audit-tools/shared";
+import type { AnalyzerResolution } from "../extractors/analyzers/types.js";
+export type AnalyzerCapabilityStatus = "applied" | "omitted";
+export interface AnalyzerCapabilityEntry {
+    id: string;
+    resolution: AnalyzerResolution;
+    setting: AnalyzerSetting;
+    edges_added: number;
+    routes_added: number;
+    note?: string;
+}
+export interface AnalyzerCapabilityRecord {
+    /** `applied` when ≥1 analyzer contributed edges/routes; `omitted` otherwise. */
+    status: AnalyzerCapabilityStatus;
+    analyzers: AnalyzerCapabilityEntry[];
+}

package/dist/types/analyzerCapability.js

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

package/dist/types/auditScope.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Phase 3 — `--since` delta scope.
+ *
+ * `scope.json` records how the audit was scoped for a given run: a full audit
+ * (the default), or a delta audit measured against a git ref. In delta mode the
+ * orchestrator audits only the changed files (`seed_files`) and their nearest
+ * graph neighbours (`expanded_files`); every other auditable file inherits its
+ * prior completion or is excluded from this run. The artifact is a deterministic
+ * function of the inputs (the ref, the changed files, the graph) so the same
+ * inputs always yield the same scope, and it is recorded honestly in the report
+ * header and the run log. It sits upstream of `coverage_matrix.json` in the
+ * staleness DAG.
+ */
+export interface AuditScopeBudget {
+    /**
+     * Upper bound on the number of in-scope files (seeds + expanded). Seeds are
+     * always retained; expansion stops once this cap is reached.
+     */
+    max_files: number;
+}
+export interface AuditScopeManifest {
+    /** `full` audits every auditable file; `delta` scopes to a changed neighbourhood. */
+    mode: "full" | "delta";
+    /** Git ref/SHA the delta was measured against; `null` in full mode. */
+    since: string | null;
+    /**
+     * Changed auditable files (relative to `since`) that exist in the repo
+     * manifest. Empty in full mode. Sorted for determinism.
+     */
+    seed_files: string[];
+    /**
+     * Auditable files pulled in by deterministic priority-frontier expansion over
+     * the dependency graph (graph neighbours of the seeds). Sorted for determinism.
+     */
+    expanded_files: string[];
+    /** The budget applied during expansion. */
+    budget: AuditScopeBudget;
+    /**
+     * Human-readable note when the scope was truncated by the budget, or when a
+     * requested `--since` could not be honoured and the run fell back to full.
+     */
+    dropped_note?: string;
+}

package/dist/types/auditScope.js

@@ -0,0 +1,14 @@
+/**
+ * Phase 3 — `--since` delta scope.
+ *
+ * `scope.json` records how the audit was scoped for a given run: a full audit
+ * (the default), or a delta audit measured against a git ref. In delta mode the
+ * orchestrator audits only the changed files (`seed_files`) and their nearest
+ * graph neighbours (`expanded_files`); every other auditable file inherits its
+ * prior completion or is excluded from this run. The artifact is a deterministic
+ * function of the inputs (the ref, the changed files, the graph) so the same
+ * inputs always yield the same scope, and it is recorded honestly in the report
+ * header and the run log. It sits upstream of `coverage_matrix.json` in the
+ * staleness DAG.
+ */
+export {};

package/dist/types/synthesisNarrative.d.ts

@@ -0,0 +1,7 @@
+export type SynthesisNarrativeStatus = "applied" | "omitted";
+export interface SynthesisNarrativeRecord {
+    status: SynthesisNarrativeStatus;
+    theme_count: number;
+    executive_summary_present: boolean;
+    top_risk_count: number;
+}

package/dist/types/synthesisNarrative.js

@@ -0,0 +1,5 @@
+// Marker artifact recording whether the optional Phase 6 synthesis-narrative
+// pass was applied or deliberately omitted. Its presence (and freshness against
+// `audit-findings.json`) satisfies the `synthesis_narrative_current` obligation;
+// the narrative content itself lives in `audit-findings.json`.
+export {};

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { Finding as SharedFinding } from "@audit-tools/shared";
 export type Lens = "correctness" | "architecture" | "maintainability" | "security" | "reliability" | "performance" | "data_integrity" | "tests" | "operability" | "config_deployment" | "observability";
 export interface FileRecord {
     path: string;
@@ -67,26 +68,8 @@ export interface AuditTask {
     completed_at?: string;
     completion_reason?: string;
 }
-export interface Finding {
-    id: string;
-    title: string;
-    category: string;
-    severity: "critical" | "high" | "medium" | "low" | "info";
-    confidence: "high" | "medium" | "low";
+export interface Finding extends Omit<SharedFinding, "lens"> {
     lens: Lens;
-    summary: string;
-    affected_files: Array<{
-        path: string;
-        line_start?: number;
-        line_end?: number;
-        symbol?: string;
-    }>;
-    impact?: string;
-    likelihood?: string;
-    evidence?: string[];
-    reproduction?: string[];
-    systemic?: boolean;
-    related_findings?: string[];
 }
 export interface AuditVerification {
     verified: boolean;

package/dist/validation/artifacts.js

@@ -19,6 +19,15 @@ export function validateArtifactBundle(bundle) {
     if (bundle.coverage_matrix) {
         issues.push(...requireKeys(bundle.coverage_matrix, "coverage_matrix", ["files"]));
     }
+    if (bundle.scope) {
+        issues.push(...requireKeys(bundle.scope, "scope", [
+            "mode",
+            "since",
+            "seed_files",
+            "expanded_files",
+            "budget",
+        ]));
+    }
     if (bundle.graph_bundle) {
         issues.push(...requireKeys(bundle.graph_bundle, "graph_bundle", ["graphs"]));
     }

package/dist/validation/sessionConfig.js

@@ -1,8 +1,9 @@
 import { spawnSync } from "node:child_process";
 import { accessSync, constants } from "node:fs";
-import { PROVIDER_NAMES, SESSION_UI_MODES, isRecord, pushValidationIssue, } from "@audit-tools/shared";
+import { ANALYZER_SETTINGS, PROVIDER_NAMES, SESSION_UI_MODES, isRecord, pushValidationIssue, } from "@audit-tools/shared";
 const VALID_PROVIDERS = new Set(PROVIDER_NAMES);
 const VALID_UI_MODES = new Set(SESSION_UI_MODES);
+const VALID_ANALYZER_SETTINGS = new Set(ANALYZER_SETTINGS);
 function pushIssue(issues, path, message) {
     pushValidationIssue(issues, path, message);
 }
@@ -158,6 +159,28 @@ export function validateSessionConfig(value) {
     validateTemplateProviderSection(value.vscode_task, "vscode_task", issues, provider === "vscode-task");
     validateAgentProviderSection(value.claude_code, "claude_code", issues);
     validateAgentProviderSection(value.opencode, "opencode", issues);
+    if (value.synthesis !== undefined) {
+        if (!isRecord(value.synthesis)) {
+            pushIssue(issues, "synthesis", "synthesis must be a JSON object.");
+        }
+        else if (value.synthesis.narrative !== undefined &&
+            typeof value.synthesis.narrative !== "boolean") {
+            pushIssue(issues, "synthesis.narrative", "synthesis.narrative must be a boolean when provided.");
+        }
+    }
+    if (value.analyzers !== undefined) {
+        if (!isRecord(value.analyzers)) {
+            pushIssue(issues, "analyzers", "analyzers must be a JSON object mapping analyzer id to a setting.");
+        }
+        else {
+            for (const [id, setting] of Object.entries(value.analyzers)) {
+                if (typeof setting !== "string" ||
+                    !VALID_ANALYZER_SETTINGS.has(setting)) {
+                    pushIssue(issues, `analyzers.${id}`, `analyzers.${id} must be one of: ${Array.from(VALID_ANALYZER_SETTINGS).join(", ")}.`);
+                }
+            }
+        }
+    }
     return issues;
 }
 export function validateConfiguredProviderEnvironment(sessionConfig, options = {}) {

package/docs/contracts.md

@@ -90,9 +90,16 @@ backend writes the current step contract to:
 includes `step_kind`, `prompt_path`, `status`, `run_id`, `allowed_commands`,
 `stop_condition`, `repo_root`, `artifacts_dir`, and relevant `artifact_paths`.
 
-When semantic review is blocked, `next-step` first emits a `capability_check`.
-After the host reports `--host-can-dispatch-subagents true|false`, the backend
-renders exactly one review path: packet dispatch or the single-task fallback.
+When semantic review is reached, the backend resolves host dispatch capability
+from `--host-can-dispatch-subagents true|false` (optional) → session config
+(`host_can_dispatch_subagents`) → `AUDIT_CODE_HOST_CAN_DISPATCH` → default
+`true`, then renders exactly one review path: packet dispatch (`dispatch_review`)
+or the single-task fallback (`single_task_fallback`). No capability handshake is
+required; pass the flag only to override the resolved default.
+
+`run-to-completion` renders the same step when it reaches the semantic-review
+boundary, so a host on the batch entrypoint can act on `steps/current-step.json`
+directly instead of issuing a second `next-step`.
 
 ## Dispatch packets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.3.41",
+  "version": "0.6.0",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",
@@ -71,6 +71,8 @@
     "@types/node": "^24.3.0",
     "ajv": "^8.17.1",
     "linguist-languages": "^9.3.2",
-    "typescript": "^5.9.2"
+    "tree-sitter-wasms": "^0.1.13",
+    "typescript": "^5.9.2",
+    "web-tree-sitter": "^0.25.10"
   }
 }