auditor-lambda 0.3.1 → 0.3.3

package/dispatch/merge-results.mjs

@@ -1,40 +1,34 @@
-import { dirname, resolve, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolve, join } from "node:path";
 import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
 import { validateResult } from "./validate.mjs";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Parse --run-id
 const runIdIdx = process.argv.indexOf("--run-id");
 if (runIdIdx === -1 || !process.argv[runIdIdx + 1]) {
   console.error("Usage: node dispatch/merge-results.mjs --run-id <run_id> [--artifacts-dir <dir>]");
   process.exit(1);
 }
-const run_id = process.argv[runIdIdx + 1];
+const runId = process.argv[runIdIdx + 1];
 
-// Parse --artifacts-dir (default: CWD/.audit-artifacts)
 const artifactsDirIdx = process.argv.indexOf("--artifacts-dir");
 const artifactsDir = artifactsDirIdx !== -1 && process.argv[artifactsDirIdx + 1]
   ? resolve(process.argv[artifactsDirIdx + 1])
   : join(process.cwd(), ".audit-artifacts");
 
-const taskResultsDir = join(artifactsDir, "runs", run_id, "task-results");
-const auditResultsPath = join(artifactsDir, "runs", run_id, "audit-results.json");
-const failedTasksPath = join(artifactsDir, "runs", run_id, "failed-tasks.json");
-const tasksPath = join(artifactsDir, "runs", run_id, "pending-audit-tasks.json");
+const taskResultsDir = join(artifactsDir, "runs", runId, "task-results");
+const auditResultsPath = join(artifactsDir, "runs", runId, "audit-results.json");
+const failedTasksPath = join(artifactsDir, "runs", runId, "failed-tasks.json");
+const tasksPath = join(artifactsDir, "runs", runId, "pending-audit-tasks.json");
 
-// Build fileLineCounts map
-const lineCounts = {};
+// Build task map for validation context
+const taskMap = {};
 if (existsSync(tasksPath)) {
   try {
     const tasks = JSON.parse(readFileSync(tasksPath, "utf8"));
     for (const task of tasks) {
-      lineCounts[task.task_id] = task.file_line_counts;
+      taskMap[task.task_id] = task;
     }
   } catch {
-    // proceed with empty map
+    // proceed without task context
   }
 }
 
@@ -59,8 +53,8 @@ for (const filename of files) {
   }
 
   const taskId = resultObj?.task_id;
-  const fileLineCounts = (taskId && lineCounts[taskId]) ? lineCounts[taskId] : {};
-  const { valid, errors } = validateResult(resultObj, fileLineCounts);
+  const task = (taskId && taskMap[taskId]) ? taskMap[taskId] : null;
+  const { valid, errors } = validateResult(resultObj, task);
 
   if (valid) {
     passing.push(resultObj);

package/dispatch/validate-result.mjs

@@ -1,38 +1,25 @@
-import { dirname, resolve, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolve, join } from "node:path";
 import { readFileSync, existsSync } from "node:fs";
 import { validateResult } from "./validate.mjs";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Support both named flags and legacy positional args:
-//   Named:    --run-id <id> --task-id <id> [--artifacts-dir <dir>]
-//   Positional (legacy): <run_id> <task_id>
-const runIdFlagIdx = process.argv.indexOf("--run-id");
-const taskIdFlagIdx = process.argv.indexOf("--task-id");
+const runIdIdx = process.argv.indexOf("--run-id");
+const taskIdIdx = process.argv.indexOf("--task-id");
 const artifactsDirIdx = process.argv.indexOf("--artifacts-dir");
 
-const run_id = runIdFlagIdx !== -1
-  ? process.argv[runIdFlagIdx + 1]
-  : process.argv[2];
-
-const task_id = taskIdFlagIdx !== -1
-  ? process.argv[taskIdFlagIdx + 1]
-  : process.argv[3];
+const runId = runIdIdx !== -1 ? process.argv[runIdIdx + 1] : undefined;
+const taskId = taskIdIdx !== -1 ? process.argv[taskIdIdx + 1] : undefined;
 
-if (!run_id || !task_id) {
+if (!runId || !taskId) {
   console.error("Usage: node dispatch/validate-result.mjs --run-id <run_id> --task-id <task_id> [--artifacts-dir <dir>]");
   process.exit(1);
 }
 
-// Artifacts dir: explicit flag > CWD default
 const artifactsDir = artifactsDirIdx !== -1 && process.argv[artifactsDirIdx + 1]
   ? resolve(process.argv[artifactsDirIdx + 1])
   : join(process.cwd(), ".audit-artifacts");
 
-const sanitized = task_id.replace(/[^a-zA-Z0-9_-]/g, "_");
-const resultPath = join(artifactsDir, "runs", run_id, "task-results", sanitized + ".json");
+const sanitized = taskId.replace(/[^a-zA-Z0-9_-]/g, "_");
+const resultPath = join(artifactsDir, "runs", runId, "task-results", sanitized + ".json");
 
 if (!existsSync(resultPath)) {
   console.error(`File not found: ${resultPath}`);
@@ -47,25 +34,24 @@ try {
   process.exit(1);
 }
 
-const tasksPath = join(artifactsDir, "runs", run_id, "pending-audit-tasks.json");
-let fileLineCounts = {};
+const tasksPath = join(artifactsDir, "runs", runId, "pending-audit-tasks.json");
+let task = null;
 if (existsSync(tasksPath)) {
   try {
     const tasks = JSON.parse(readFileSync(tasksPath, "utf8"));
-    const task = tasks.find(t => t.task_id === task_id);
-    fileLineCounts = task?.file_line_counts ?? {};
+    task = tasks.find(t => t.task_id === taskId) ?? null;
   } catch {
-    // use empty
+    // proceed without task context
   }
 }
 
-const { valid, errors } = validateResult(resultObj, fileLineCounts);
+const { valid, errors } = validateResult(resultObj, task);
 
 if (valid) {
-  console.log("✓ valid:", task_id);
+  console.log("✓ valid:", taskId);
   process.exit(0);
 } else {
-  console.error("✗ invalid:", task_id);
+  console.error("✗ invalid:", taskId);
   console.error(JSON.stringify(errors, null, 2));
   process.exit(1);
 }

package/dispatch/validate.mjs

@@ -1,88 +1,16 @@
-import { dirname, resolve, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { readFileSync } from "node:fs";
-import Ajv2020 from "ajv/dist/2020.js";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const PROJECT_ROOT = resolve(__dirname, "..");
-const SCHEMAS_DIR = join(PROJECT_ROOT, "schemas");
-
-function loadSchema(name) {
-  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), "utf8"));
-}
-
-let _ajv = null;
-let _validateFn = null;
-
-function getValidator() {
-  if (_validateFn) return _validateFn;
-  _ajv = new Ajv2020({ strict: false, allErrors: true });
-  _ajv.addSchema(loadSchema("finding.schema.json"));
-  _validateFn = _ajv.compile(loadSchema("audit_result.schema.json"));
-  return _validateFn;
-}
-
-function formatAjvError(e) {
-  const path = e.instancePath || "(root)";
-  return `${path}: ${e.message}${e.params ? " (" + JSON.stringify(e.params) + ")" : ""}`;
-}
+import { validateAuditResults } from "../dist/validation/auditResults.js";
 
 /**
  * @param {object} resultObj  — parsed JSON from a task-results file
- * @param {Record<string, number>} fileLineCounts — from the task's file_line_counts
+ * @param {object|null} task  — the matching AuditTask from pending-audit-tasks.json, or null
  * @returns {{ valid: boolean, errors: string[] }}
  */
-export function validateResult(resultObj, fileLineCounts) {
-  const validate = getValidator();
-  const schemaValid = validate(resultObj);
-
-  if (!schemaValid) {
-    return { valid: false, errors: validate.errors.map(formatAjvError) };
-  }
-
-  const errors = [];
-
-  // Line range constraint
-  for (const finding of resultObj.findings) {
-    for (const entry of finding.affected_files) {
-      if (entry.line_end !== undefined) {
-        const coverage = resultObj.file_coverage.find(fc => fc.path === entry.path);
-        if (!coverage) {
-          errors.push(`affected_files path '${entry.path}' not in file_coverage`);
-        } else if (entry.line_end > coverage.total_lines) {
-          errors.push(
-            `finding '${finding.id}': line_end ${entry.line_end} exceeds total_lines ${coverage.total_lines} for ${entry.path}`
-          );
-        }
-      }
-    }
-  }
-
-  // Lens consistency
-  for (const finding of resultObj.findings) {
-    if (finding.lens !== resultObj.lens) {
-      errors.push(
-        `finding '${finding.id}': lens '${finding.lens}' does not match task lens '${resultObj.lens}'`
-      );
-    }
-  }
-
-  // affected_files paths in scope
-  const allowedPaths = new Set(resultObj.file_coverage.map(fc => fc.path));
-  for (const finding of resultObj.findings) {
-    for (const entry of finding.affected_files) {
-      if (!allowedPaths.has(entry.path)) {
-        errors.push(
-          `finding '${finding.id}': affected path '${entry.path}' not in task file_coverage`
-        );
-      }
-    }
-  }
-
-  if (errors.length > 0) {
-    return { valid: false, errors };
-  }
-
-  return { valid: true, errors: [] };
+export function validateResult(resultObj, task) {
+  const tasks = task ? [task] : [];
+  const lineIndex = task?.file_line_counts ?? {};
+  const issues = validateAuditResults([resultObj], tasks, { lineIndex });
+  const errors = issues
+    .filter(i => i.severity === "error")
+    .map(i => `${i.path}: ${i.message}`);
+  return { valid: errors.length === 0, errors };
 }

package/dist/cli.js

@@ -1312,6 +1312,9 @@ async function cmdRunToCompletion(argv) {
         next_likely_step: state.status === "complete" ? null : decision.selected_obligation,
         providerName: provider.name,
     });
+    if (state.status === "complete") {
+        await promoteFinalAuditReport({ artifactsDir, repoRoot: root });
+    }
 }
 async function cmdWorkerRun(argv) {
     const taskPath = getFlag(argv, "--task");
@@ -1451,6 +1454,8 @@ async function cmdPrepareDispatch(argv) {
             "",
             "## Output",
             `Write a single JSON object to: ${outputPath}`,
+            "Write only this assigned task's AuditResult object. Do not edit source files,",
+            "remediate findings, create extra task results, or run unrelated audits.",
             "",
             "Required fields:",
             "  task_id       copy from task metadata above",
@@ -1501,18 +1506,23 @@ async function cmdMergeAndIngest(argv) {
     const taskResultsDir = join(runDir, "task-results");
     const auditResultsPath = join(runDir, "audit-results.json");
     const taskPath = join(runDir, "task.json");
-    // Merge: collect all per-task result files (skip .prompt.md files)
+    const tasksPath = join(runDir, "pending-audit-tasks.json");
+    let allTasks = [];
+    try {
+        allTasks = await readJsonFile(tasksPath);
+    }
+    catch { /* may not exist */ }
+    const taskMap = new Map(allTasks.map(t => [t.task_id, t]));
     let files;
     try {
-        files = (await readdir(taskResultsDir))
-            .filter(f => f.endsWith(".json"))
-            .sort();
+        files = (await readdir(taskResultsDir)).filter(f => f.endsWith(".json")).sort();
     }
     catch {
         files = [];
     }
     const passing = [];
     const failing = [];
+    const seenTaskIds = new Set();
     for (const filename of files) {
         const filePath = join(taskResultsDir, filename);
         let obj;
@@ -1523,30 +1533,39 @@ async function cmdMergeAndIngest(argv) {
             failing.push({ task_id: filename, errors: [`Invalid JSON: ${e.message}`] });
             continue;
         }
-        const r = obj;
-        const missing = ["task_id", "unit_id", "pass_id", "lens", "file_coverage", "findings"].filter(f => !(f in r));
-        if (missing.length > 0) {
-            failing.push({ task_id: String(r.task_id ?? filename), errors: [`Missing required fields: ${missing.join(", ")}`] });
+        const taskId = typeof obj.task_id === "string"
+            ? String(obj.task_id) : undefined;
+        if (taskId) {
+            seenTaskIds.add(taskId);
         }
-        else {
+        const matchingTask = taskId ? taskMap.get(taskId) : undefined;
+        const issues = validateAuditResults([obj], matchingTask ? [matchingTask] : [], { lineIndex: matchingTask?.file_line_counts ?? {} });
+        const errors = issues.filter(i => i.severity === "error");
+        if (errors.length === 0) {
             passing.push(obj);
         }
+        else {
+            failing.push({ task_id: taskId ?? filename, errors: errors.map(i => i.message) });
+        }
+    }
+    for (const task of allTasks) {
+        if (!seenTaskIds.has(task.task_id)) {
+            failing.push({
+                task_id: task.task_id,
+                errors: ["Missing audit result for assigned task."],
+            });
+        }
     }
     await writeJsonFile(auditResultsPath, passing);
     if (failing.length > 0) {
-        await writeJsonFile(join(runDir, "failed-tasks.json"), failing);
-        process.stderr.write(`${failing.length} task(s) excluded — see ${join(runDir, "failed-tasks.json")}\n`);
+        const failedTasksPath = join(runDir, "failed-tasks.json");
+        await writeJsonFile(failedTasksPath, failing);
+        throw new Error(`${failing.length} assigned task result(s) were missing or invalid; blocked before ingestion. See ${failedTasksPath}`);
     }
     process.stderr.write(`✓ ${passing.length}/${files.length} results merged → ${auditResultsPath}\n`);
     // Ingest: run worker-run logic against the merged results file
     await cmdWorkerRun([argv[0], argv[1], "worker-run", "--task", taskPath, "--artifacts-dir", artifactsDir]);
 }
-const VALID_LENSES_SET = new Set([
-    "correctness", "architecture", "maintainability", "security", "reliability",
-    "performance", "data_integrity", "tests", "operability", "config_deployment",
-]);
-const VALID_SEVERITIES_SET = new Set(["critical", "high", "medium", "low", "info"]);
-const VALID_CONFIDENCES_SET = new Set(["high", "medium", "low"]);
 async function cmdValidateResult(argv) {
     const runId = getFlag(argv, "--run-id");
     const taskId = getFlag(argv, "--task-id");
@@ -1574,102 +1593,22 @@ async function cmdValidateResult(argv) {
         process.exitCode = 1;
         return;
     }
-    const errors = [];
-    // Required top-level fields
-    for (const field of ["task_id", "unit_id", "pass_id", "lens", "file_coverage", "findings"]) {
-        if (!(field in obj))
-            errors.push(`Missing required field: ${field}`);
-    }
-    if (errors.length > 0) {
-        console.error(`✗ invalid: ${taskId}`);
-        for (const e of errors)
-            console.error(`  ${e}`);
-        process.exitCode = 1;
-        return;
-    }
-    // Lens
-    if (typeof obj.lens !== "string" || !VALID_LENSES_SET.has(obj.lens)) {
-        errors.push(`lens must be one of: ${[...VALID_LENSES_SET].join("|")}`);
-    }
-    // file_coverage
-    if (!Array.isArray(obj.file_coverage) || obj.file_coverage.length === 0) {
-        errors.push("file_coverage must be a non-empty array");
-    }
-    else {
-        for (const fc of obj.file_coverage) {
-            const entry = fc;
-            if (typeof entry.path !== "string")
-                errors.push(`file_coverage entry missing string 'path'`);
-            if (typeof entry.total_lines !== "number")
-                errors.push(`file_coverage entry missing numeric 'total_lines'`);
-        }
-    }
-    // findings
-    if (!Array.isArray(obj.findings)) {
-        errors.push("findings must be an array");
-    }
-    else {
-        for (const f of obj.findings) {
-            const finding = f;
-            for (const field of ["id", "title", "category", "severity", "confidence", "lens", "summary"]) {
-                if (typeof finding[field] !== "string")
-                    errors.push(`finding missing string '${field}'`);
-            }
-            if (typeof finding.severity === "string" && !VALID_SEVERITIES_SET.has(finding.severity)) {
-                errors.push(`finding '${finding.id}': invalid severity '${finding.severity}'`);
-            }
-            if (typeof finding.confidence === "string" && !VALID_CONFIDENCES_SET.has(finding.confidence)) {
-                errors.push(`finding '${finding.id}': invalid confidence '${finding.confidence}'`);
-            }
-            if (!Array.isArray(finding.affected_files) || finding.affected_files.length === 0) {
-                errors.push(`finding '${finding.id}': affected_files must be a non-empty array`);
-            }
-            else {
-                for (const af of finding.affected_files) {
-                    if (typeof af.path !== "string") {
-                        errors.push(`finding '${finding.id}': affected_files entries must be objects with a 'path' key`);
-                    }
-                }
-            }
-            if (!Array.isArray(finding.evidence) || finding.evidence.length === 0) {
-                errors.push(`finding '${finding.id}': evidence must be a non-empty array`);
-            }
-            if (typeof finding.lens === "string" && finding.lens !== obj.lens) {
-                errors.push(`finding '${finding.id}': lens '${finding.lens}' does not match task lens '${obj.lens}'`);
-            }
-        }
-    }
-    // Line range bounds (load from pending-audit-tasks.json if available)
-    let fileLineCounts = {};
+    let allTasks = [];
     try {
-        const tasks = await readJsonFile(tasksPath);
-        const task = tasks.find(t => t.task_id === taskId);
-        fileLineCounts = task?.file_line_counts ?? {};
-    }
-    catch { /* ignore */ }
-    if (Array.isArray(obj.file_coverage) && Array.isArray(obj.findings)) {
-        const coverageMap = new Map(obj.file_coverage.map(fc => [fc.path, fc.total_lines]));
-        const allowedPaths = new Set(coverageMap.keys());
-        for (const f of obj.findings) {
-            for (const af of (f.affected_files ?? [])) {
-                const p = af.path;
-                if (!allowedPaths.has(p))
-                    errors.push(`finding '${f.id}': path '${p}' not in file_coverage`);
-                if (typeof af.line_end === "number") {
-                    const max = coverageMap.get(p) ?? fileLineCounts[p] ?? Infinity;
-                    if (af.line_end > max)
-                        errors.push(`finding '${f.id}': line_end ${af.line_end} exceeds total_lines ${max} for ${p}`);
-                }
-            }
-        }
+        allTasks = await readJsonFile(tasksPath);
     }
+    catch { /* may not exist */ }
+    const matchingTasks = allTasks.filter(t => t.task_id === taskId);
+    const lineIndex = matchingTasks[0]?.file_line_counts ?? {};
+    const issues = validateAuditResults([obj], matchingTasks, { lineIndex });
+    const errors = issues.filter(i => i.severity === "error");
     if (errors.length === 0) {
         console.log(`✓ valid: ${taskId}`);
     }
     else {
         console.error(`✗ invalid: ${taskId}`);
         for (const e of errors)
-            console.error(`  ${e}`);
+            console.error(`  ${e.path}: ${e.message}`);
         process.exitCode = 1;
     }
 }

package/dist/io/json.js

@@ -29,7 +29,7 @@ export async function readJsonFile(path) {
         if (isFileMissingError(error)) {
             throw error;
         }
-        throw new Error(`Failed to read ${path}: ${errorMessage(error)}`);
+        throw ioError("read", path, error);
     }
     try {
         return JSON.parse(content);
@@ -82,7 +82,7 @@ export async function readNdjsonFile(path) {
         if (error instanceof Error && error.message.includes(path)) {
             throw error;
         }
-        throw new Error(`Failed to read ${path}: ${errorMessage(error)}`);
+        throw ioError("read", path, error);
     }
 }
 export async function readOptionalJsonFile(path) {
@@ -128,7 +128,7 @@ export async function readOptionalTextFile(path) {
         if (isFileMissingError(error)) {
             return undefined;
         }
-        throw new Error(`Failed to read ${path}: ${errorMessage(error)}`);
+        throw ioError("read", path, error);
     }
 }
 export async function writeTextFile(path, value) {

package/dist/io/runArtifacts.js

@@ -5,11 +5,13 @@ import { writeJsonFile } from "./json.js";
 const moduleDir = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(moduleDir, "..", "..");
 const auditResultSchemaPath = join(packageRoot, "schemas", "audit_result.schema.json");
+const auditResultsSchemaPath = join(packageRoot, "schemas", "audit_results.schema.json");
 const findingSchemaPath = join(packageRoot, "schemas", "finding.schema.json");
 const CURRENT_TASK_FILENAME = "current-task.json";
 const CURRENT_PROMPT_FILENAME = "current-prompt.md";
 const CURRENT_TASKS_FILENAME = "current-tasks.json";
 const CURRENT_SCHEMA_FILENAME = "audit-result.schema.json";
+const CURRENT_RESULTS_SCHEMA_FILENAME = "audit-results.schema.json";
 const CURRENT_FINDING_SCHEMA_FILENAME = "finding.schema.json";
 function pad(value, size = 2) {
     return String(value).padStart(size, "0");
@@ -58,6 +60,7 @@ export async function ensureSupervisorDirs(artifactsDir) {
 async function writeDispatchSchemaFiles(artifactsDir) {
     const dispatchDir = join(artifactsDir, "dispatch");
     await writeFile(join(dispatchDir, CURRENT_SCHEMA_FILENAME), await readFile(auditResultSchemaPath, "utf8"), "utf8");
+    await writeFile(join(dispatchDir, CURRENT_RESULTS_SCHEMA_FILENAME), await readFile(auditResultsSchemaPath, "utf8"), "utf8");
     await writeFile(join(dispatchDir, CURRENT_FINDING_SCHEMA_FILENAME), await readFile(findingSchemaPath, "utf8"), "utf8");
 }
 export async function writeWorkerTaskFiles(task, prompt, paths, artifactsDir, currentTasks, options = {}) {
@@ -119,6 +122,7 @@ export async function clearDispatchFiles(artifactsDir) {
         CURRENT_PROMPT_FILENAME,
         CURRENT_TASKS_FILENAME,
         CURRENT_SCHEMA_FILENAME,
+        CURRENT_RESULTS_SCHEMA_FILENAME,
         CURRENT_FINDING_SCHEMA_FILENAME,
     ];
     for (const name of targets) {

package/dist/mcp/server.js

@@ -14,6 +14,7 @@ const packageRoot = resolve(moduleDir, "..", "..");
 const wrapperPath = join(packageRoot, "audit-code.mjs");
 const packageJsonPath = join(packageRoot, "package.json");
 const PROTOCOL_VERSION = "2025-06-18";
+const MAX_CONTENT_LENGTH_BYTES = 10 * 1024 * 1024;
 function getFlag(argv, name) {
     const index = argv.indexOf(name);
     if (index < 0)
@@ -68,6 +69,22 @@ function failure(id, code, message, data) {
         },
     };
 }
+function parseContentLength(headerBlock) {
+    const headers = headerBlock.split("\r\n");
+    const contentLengthHeader = headers.find((header) => header.toLowerCase().startsWith("content-length:"));
+    if (!contentLengthHeader) {
+        throw new Error("missing Content-Length");
+    }
+    const rawValue = contentLengthHeader.split(":")[1]?.trim();
+    const contentLength = Number(rawValue);
+    if (rawValue?.length === 0 ||
+        !Number.isInteger(contentLength) ||
+        contentLength < 0 ||
+        contentLength > MAX_CONTENT_LENGTH_BYTES) {
+        throw new Error("bad Content-Length");
+    }
+    return contentLength;
+}
 async function runWrapperCommand(args, options) {
     return await new Promise((resolvePromise, rejectPromise) => {
         const child = spawn(process.execPath, [
@@ -419,21 +436,17 @@ export async function runAuditCodeMcpServer(argv) {
             if (separator < 0) {
                 return;
             }
-            const headerBlock = buffer.slice(0, separator).toString("utf8");
-            const headers = headerBlock.split("\r\n");
-            const contentLengthHeader = headers.find((header) => header.toLowerCase().startsWith("content-length:"));
-            if (!contentLengthHeader) {
-                buffer = Buffer.alloc(0);
-                writeMessage(failure(null, -32700, "Invalid MCP framing: missing Content-Length."));
-                return;
+            let contentLength;
+            try {
+                const headerBlock = buffer.slice(0, separator).toString("utf8");
+                contentLength = parseContentLength(headerBlock);
             }
-            const contentLength = Number(contentLengthHeader.split(":")[1]?.trim());
-            const frameLength = separator + 4 + contentLength;
-            if (!Number.isFinite(contentLength) || contentLength < 0) {
+            catch (error) {
                 buffer = Buffer.alloc(0);
-                writeMessage(failure(null, -32700, "Invalid MCP framing: bad Content-Length."));
+                writeMessage(failure(null, -32700, `Invalid MCP framing: ${error instanceof Error ? error.message : String(error)}.`));
                 return;
             }
+            const frameLength = separator + 4 + contentLength;
             if (buffer.length < frameLength) {
                 return;
             }

package/dist/orchestrator.js

@@ -10,9 +10,60 @@ const DEFAULT_LENS_ORDER = [
     "operability",
     "config_deployment",
 ];
+const VALID_LENSES = new Set(DEFAULT_LENS_ORDER);
+function isRecord(value) {
+    return value !== null && typeof value === "object";
+}
+function isLens(value) {
+    return typeof value === "string" && VALID_LENSES.has(value);
+}
+function assertStringArray(value, label) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new TypeError(`${label} must be an array of strings.`);
+    }
+}
+function assertLensArray(value, label) {
+    if (!Array.isArray(value) || value.some((item) => !isLens(item))) {
+        throw new TypeError(`${label} must be an array of supported lenses.`);
+    }
+}
+function assertUnitManifest(value) {
+    if (!isRecord(value) || !Array.isArray(value.units)) {
+        throw new TypeError("buildAuditTasks requires unitManifest.units to be an array.");
+    }
+    value.units.forEach((unit, index) => {
+        const label = `unitManifest.units[${index}]`;
+        if (!isRecord(unit)) {
+            throw new TypeError(`${label} must be an object.`);
+        }
+        if (typeof unit.unit_id !== "string" || unit.unit_id.length === 0) {
+            throw new TypeError(`${label}.unit_id must be a non-empty string.`);
+        }
+        if (typeof unit.name !== "string" || unit.name.length === 0) {
+            throw new TypeError(`${label}.name must be a non-empty string.`);
+        }
+        assertStringArray(unit.files, `${label}.files`);
+        assertLensArray(unit.required_lenses, `${label}.required_lenses`);
+    });
+}
+function normalizedOptions(options) {
+    if (!isRecord(options)) {
+        throw new TypeError("buildAuditTasks options must be an object.");
+    }
+    if (options.pass_prefix !== undefined && typeof options.pass_prefix !== "string") {
+        throw new TypeError("buildAuditTasks options.pass_prefix must be a string.");
+    }
+    if (options.limit_lenses !== undefined) {
+        assertLensArray(options.limit_lenses, "buildAuditTasks options.limit_lenses");
+    }
+    return {
+        passPrefix: options.pass_prefix ?? "pass",
+        allowed: new Set(options.limit_lenses ?? DEFAULT_LENS_ORDER),
+    };
+}
 export function buildAuditTasks(unitManifest, options = {}) {
-    const allowed = new Set(options.limit_lenses ?? DEFAULT_LENS_ORDER);
-    const passPrefix = options.pass_prefix ?? "pass";
+    assertUnitManifest(unitManifest);
+    const { allowed, passPrefix } = normalizedOptions(options);
     const tasks = [];
     for (const unit of unitManifest.units) {
         for (const lens of unit.required_lenses) {

package/dist/prompts/renderWorkerPrompt.js

@@ -7,11 +7,17 @@ export function renderWorkerPrompt(task) {
     if (task.preferred_executor === "agent" && task.audit_results_path) {
         const tasksPath = task.pending_audit_tasks_path ??
             `${task.artifacts_dir}/audit_tasks.json`;
+        const resultsSchemaPath = `${task.artifacts_dir}/dispatch/audit-results.schema.json`;
+        const singleResultSchemaPath = `${task.artifacts_dir}/dispatch/audit-result.schema.json`;
         const lines = [
             `Audit run: ${task.run_id}`,
             `Read: ${tasksPath}`,
-            "For each task: read all file_paths in full, review under the specified lens,",
-            "and emit one AuditResult with:",
+            `Array schema: ${resultsSchemaPath}`,
+            `Single-result schema: ${singleResultSchemaPath}`,
+            "Scope: review only the tasks listed in the Read file. Do not add tasks,",
+            "edit source files, remediate findings, run unrelated audits, or write result_path.",
+            "For each listed task: read all file_paths in full, review under the specified lens,",
+            "and emit exactly one AuditResult object with:",
             "  task_id, unit_id, pass_id, lens (copy from task),",
             "  file_coverage: [{path, total_lines}] — use file_line_counts[path] from the task for each file,",
             "  findings: [] or array of finding objects.",
@@ -19,13 +25,13 @@ export function renderWorkerPrompt(task) {
             "  affected_files [{path, line_start, line_end, symbol}] (objects, not strings; min 1 entry),",
             "  evidence [strings] (min 1 entry).",
             "Constraint: line_end must not exceed total_lines for that file.",
-            `Write all results as a JSON array to: ${task.audit_results_path}`,
+            `Write only the JSON array of AuditResult objects to: ${task.audit_results_path}`,
         ];
         if (usesDeferredWorkerCommand(task)) {
             lines.push("Deferred mode: write results, do not execute worker_command.");
         }
         else {
-            lines.push("Then execute worker_command from task.json exactly.", `Command: ${commandArgv}`);
+            lines.push("After writing audit_results_path, execute worker_command from task.json exactly.", "The worker command ingests audit_results_path and writes result_path.", `Command: ${commandArgv}`);
         }
         return lines.join("\n");
     }

package/dist/providers/index.js

@@ -21,7 +21,7 @@ function commandExists(command) {
     return result.status === 0;
 }
 export function resolveFreshSessionProviderName(name, sessionConfig = {}, options = {}) {
-    const requestedProvider = name ?? sessionConfig.provider ?? "auto";
+    const requestedProvider = name ?? sessionConfig.provider ?? "local-subprocess";
     if (requestedProvider !== "auto") {
         return requestedProvider;
     }

package/dist/supervisor/sessionConfig.js

@@ -4,7 +4,7 @@ import { formatValidationIssues, } from "../validation/basic.js";
 import { validateSessionConfig } from "../validation/sessionConfig.js";
 import { writeJsonFile } from "../io/json.js";
 const SESSION_CONFIG_FILENAME = "session-config.json";
-const DEFAULT_SESSION_CONFIG = { provider: "auto" };
+const DEFAULT_SESSION_CONFIG = { provider: "local-subprocess" };
 export function getSessionConfigPath(artifactsDir) {
     return join(artifactsDir, SESSION_CONFIG_FILENAME);
 }

package/dist/validation/sessionConfig.js

@@ -156,7 +156,7 @@ export function validateConfiguredProviderEnvironment(sessionConfig, options = {
     const issues = [];
     const lookupCommand = options.commandExists ?? commandExists;
     const lookupPath = options.pathExists ?? configuredPathExists;
-    const provider = sessionConfig.provider ?? "auto";
+    const provider = sessionConfig.provider ?? "local-subprocess";
     if (provider === "claude-code") {
         const command = sessionConfig.claude_code?.command ?? "claude";
         if (isBareExecutableName(command) && !lookupCommand(command)) {

package/docs/agent-integrations.md

@@ -120,13 +120,13 @@ Use the backend wrapper only when you intentionally need the repo-local fallback
 
 ## What the wrapper actually does
 
-`audit-code` is the stable backend entrypoint.
+`audit-code` is the stable backend entrypoint behind the slash command.
 
 It:
 
 - defaults artifacts to `<repo-root>/.audit-artifacts`
 - persists audit continuity there
-- calls `run-to-completion` by default
+- calls `run-to-completion` by default for deterministic work
 - creates fresh worker runs behind the scenes
 - returns a stable top-level JSON contract with `contract_version: "audit-code/v1alpha1"`
 
@@ -145,13 +145,15 @@ Inspect the returned JSON and continue invoking the same entrypoint until either
 Terminal interpretation:
 
 - `audit_state.status === "complete"` means the audit finished end to end.
-- `audit_state.status === "blocked"` means the wrapper exhausted automatic work and the remaining review still needs imported results or a provider-capable continuation path.
+- `audit_state.status === "blocked"` means the wrapper exhausted deterministic
+  work and exposed scoped semantic-review task artifacts for the slash-command
+  orchestrator.
 
 Current implementation note:
 
 - the backend fallback still supports explicit provider bridges such as `claude-code`, `opencode`, `subprocess-template`, and `vscode-task`
 - those bridges are compatibility modes, not the intended default review owner
-- the intended long-term workflow is documented in [docs/workflow-refactor-brief.md](/C:/Code/auditor-lambda/docs/workflow-refactor-brief.md)
+- the intended workflow is documented in [docs/workflow-refactor-brief.md](/C:/Code/auditor-lambda/docs/workflow-refactor-brief.md)
 
 When additional evidence exists, pass it into the same wrapper:
 
@@ -172,9 +174,15 @@ Use it when the current host cannot keep review inside the active conversation,
 
 Use when you want the supervisor to stay entirely local.
 
-This requires no external agent CLI. Deterministic executors run in-process during normal wrapper runs, and the supervisor only stops once the remaining work is genuinely semantic review.
+This requires no external agent CLI. Deterministic executors run in-process
+during normal wrapper runs, and the supervisor only stops once the remaining
+work is genuinely semantic review.
 
-When that review boundary is reached, `local-subprocess` stops in a terminal blocked handoff instead of pretending more automatic progress is available. Use `--results <file>` for a single batch or `--batch-results <dir>` when the active conversation agent reviewed multiple task batches before ingestion.
+When that review boundary is reached, `local-subprocess` stops in a terminal
+blocked handoff instead of pretending more automatic progress is available.
+The slash-command orchestrator should dispatch subagents from the handoff when
+available; otherwise it should review exactly one task, write results, run the
+provided worker command, and stop.
 
 This is the safest default backend when the repository is already available locally.
 
@@ -255,7 +263,8 @@ Highest-value follow-through:
 
 The product direction remains skill-first:
 
-- in conversation, use the active conversation model by default
+- in conversation, keep orchestration in the active model and delegate semantic
+  review to bounded subagents when the host supports them
 - for backend CLI delegation, let the chosen provider own its own model-selection behavior unless explicitly configured otherwise
 
 ## Practical recommendation
@@ -265,7 +274,7 @@ For a polished operator experience today:
 1. treat `/audit-code` as the canonical user-facing contract
 2. use `audit-code install` first, and fall back to `audit-code prompt-path` only for hosts that still require manual prompt import
 3. use `audit-code` as the repo-local backend fallback
-4. prefer `local-subprocess` unless you want interactive review to continue automatically through agent tasks
+4. prefer `local-subprocess` unless you explicitly want a backend provider bridge
 5. use `subprocess-template` only when integrating a non-native editor or launcher surface
 
 If you intentionally want the backend fallback to bridge semantic review into another process, re-run with an explicit `--provider` flag after configuring the matching section in `.audit-artifacts/session-config.json`.

package/docs/session-config.md

@@ -88,7 +88,8 @@ How many provider-assisted review batches to launch in parallel when the selecte
 
 This setting only applies to explicit backend bridge launches.
 
-It should not be treated as the source of truth for in-conversation subagent parallelism, which belongs to the active conversation agent or host runtime.
+It should not be treated as the source of truth for slash-command subagent
+parallelism, which belongs to the host runtime.
 
 ## Auto provider mode
 
@@ -112,7 +113,10 @@ This keeps the current default stable while still allowing best-effort cross-edi
 
 No extra config is required.
 
-This mode covers deterministic audit execution locally and stops in a terminal blocked state once the remaining work requires imported audit results or an interactive provider.
+This mode covers deterministic audit execution locally and stops in a terminal
+blocked state once the remaining work requires semantic review. The
+slash-command orchestrator should then dispatch bounded subagents when the host
+supports them, or complete one assigned task and stop when it does not.
 
 When the active conversation agent reviews multiple task batches before ingestion, prefer `audit-code --batch-results <dir>` over ad hoc artifact edits.
 

package/docs/supervisor.md

@@ -6,8 +6,13 @@ The primary product contract is `/audit-code` in conversation.
 
 Everything here is fallback and implementation detail guidance for the repo-local backend surface.
 
-In the intended workflow, the active conversation agent owns semantic review.
-Provider adapters are compatibility bridges for backend fallback mode, not the default review owner.
+In the intended workflow, the conversation agent owns orchestration and
+ingestion control, but bounded subagents own semantic review whenever the host
+can dispatch them. If subagents are unavailable, the conversation agent reviews
+one assigned task and stops so `/audit-code` can be rerun from fresh context.
+
+Provider adapters are compatibility bridges for backend fallback mode, not the
+default review owner.
 
 ## Repo-local backend surface
 
@@ -59,7 +64,8 @@ audit-code --provider vscode-task
 ```
 
 Those `--provider` invocations are the explicit bridge handoff point.
-Without an explicit `--provider` flag, the backend keeps semantic review with the active conversation agent and uses `local-subprocess` only for deterministic worker steps.
+Without an explicit `--provider` flag, the backend stops at the semantic-review
+boundary and exposes scoped task artifacts for the slash-command orchestrator.
 
 ## Auto resolution rule
 
@@ -87,4 +93,6 @@ See:
 ## Note
 
 Provider adapters are backend integrations, not the primary product concept.
-Session config defines bridge settings, but the explicit `--provider` flag is what opts the backend into owning semantic-review dispatch.
+Session config defines bridge settings. An explicit `provider: "auto"` or
+`--provider` bridge selection is what opts the backend into provider-mediated
+review dispatch.

package/docs/workflow-refactor-brief.md

@@ -16,13 +16,16 @@ That is not the intended workflow.
 
 The intended `/audit-code` workflow is:
 
-1. The active conversation agent owns semantic review work.
-2. Deterministic planning computes which files need which lenses.
-3. Pending review is partitioned into non-overlapping review blocks, preferably grouped by lens.
-4. One dispatched review task should correspond to one review block.
-5. `agent_task_batch_size` should stay `1` by default.
-6. If the active conversation agent can delegate to subagents in parallel, that fan-out belongs to the host agent runtime, not to the backend session config.
-7. Backend provider adapters are fallback compatibility bridges only. They should not be the default review owner.
+1. The active conversation agent owns orchestration and ingestion control.
+2. Bounded subagents own semantic review work whenever the host supports them.
+3. If subagents are unavailable, the conversation agent completes one assigned
+   review task and stops so `/audit-code` can be rerun from fresh context.
+4. Deterministic planning computes which files need which lenses.
+5. Pending review is partitioned into non-overlapping review blocks, preferably grouped by lens.
+6. One dispatched review task should correspond to one review block.
+7. `agent_task_batch_size` should stay `1` by default.
+8. Subagent fan-out belongs to the host agent runtime, not to the backend session config.
+9. Backend provider adapters are fallback compatibility bridges only. They should not be the default review owner.
 
 ## Current implementation drift
 
@@ -97,15 +100,19 @@ That fan-out is consistent with the current unit-first planner, not with the int
 
 The next implementation pass should do the following.
 
-### A. Make the active conversation agent the semantic-review owner
+### A. Make the slash-command orchestrator the review dispatcher
 
-The `agent` executor should represent review work owned by the current conversation or host agent session.
+The `agent` executor should represent review work owned by the current
+conversation or host agent session, with semantic review delegated to bounded
+subagents whenever possible.
 
 Target behavior:
 
 - normal `/audit-code` usage does not require `provider: "claude-code"` or `provider: "opencode"`
 - session-config should not be the normal way to choose a second LLM for review
 - backend provider bridges remain available only for explicit fallback workflows
+- when subagents are unavailable, one invocation performs at most one semantic
+  review task before stopping
 
 ### B. Plan review work at the file/lens level
 
@@ -150,6 +157,8 @@ Relevant files:
 The refactor should be treated as done only when all of the following are true.
 
 - Starting `/audit-code` in a conversation does not rely on an external `claude-code` or `opencode` subprocess to own semantic review.
+- The slash-command orchestrator dispatches bounded subagents when available and
+  falls back to one semantic review task per invocation otherwise.
 - The backend fallback still supports deterministic stages and explicit compatibility bridges.
 - The default dispatch granularity for semantic review remains one review block per task.
 - Pending review tasks are planned as lens-aware, non-overlapping file blocks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",
@@ -38,7 +38,7 @@
     "start": "node dist/index.js",
     "audit-code": "node audit-code.mjs",
     "sample-run": "node dist/index.js sample-run",
-    "dispatch:prepare": "node dispatch/prepare-dispatch.mjs",
+    "dispatch:prepare": "node audit-code.mjs prepare-dispatch",
     "dispatch:merge": "node dispatch/merge-results.mjs",
     "dispatch:validate": "node dispatch/validate-result.mjs"
   },

package/schemas/audit_results.schema.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "audit_results.schema.json",
+  "title": "Audit Results",
+  "type": "array",
+  "minItems": 1,
+  "items": {
+    "$ref": "audit_result.schema.json"
+  }
+}

package/skills/audit-code/SKILL.md

@@ -17,8 +17,16 @@ Normal usage should:
 - avoid manual paths, provider flags, and model-selection arguments
 - advance the audit automatically until it completes or no further automatic progress is possible
 
-Semantic review should stay with the active conversation agent by default.
-If the host can delegate to subagents, that fan-out belongs to the host agent runtime rather than to repo-local backend provider settings.
+Semantic review should be delegated to bounded subagents whenever the host can
+dispatch them. The conversation orchestrator owns dispatch and ingestion control;
+it should not perform broad review itself when subagents are available.
+
+If the host cannot delegate to subagents, the conversation orchestrator may
+complete exactly one assigned review task, ingest it through the provided backend
+command, then stop so the user can rerun `/audit-code` from fresh context.
+
+Subagent fan-out belongs to the host agent runtime rather than to repo-local
+backend provider settings.
 
 Bounded steps are a backend implementation detail, not the intended user experience.
 
@@ -66,7 +74,8 @@ audit-code --single-step
 For repo-local backend usage:
 
 - omitted provider remains `local-subprocess`
-- `local-subprocess` should stop cleanly once only manual or provider-assisted review remains
+- `local-subprocess` should stop cleanly once semantic review is needed and
+  expose scoped task artifacts for the slash-command orchestrator
 - `provider: "auto"` is the explicit opt-in best-effort routing mode
 - explicit provider names remain available when an operator wants a specific backend
 

package/skills/audit-code/audit-code.prompt.md

@@ -1,22 +1,37 @@
 ---
-description: Autonomous local loop code auditing — steps the audit-code orchestrator and dispatches parallel subagents until the audit completes
+description: Autonomous local loop code auditing - advances deterministic audit state, delegates bounded review tasks, and ingests validated results
 argument-hint: [target-dir]
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent]
+allowed-tools: [Read, Write, Bash, Glob, Grep, Agent]
 ---
 
 # `/audit-code` Execution Directive
 
-**SYSTEM DIRECTIVE:** You are the autonomous audit orchestrator. Your job is to advance the state machine, dispatch parallel subagents for code review work, and loop until the audit is complete. Do not ask the user for confirmation between steps.
-
----
-
-## The Loop
-
-Repeat Steps 1–5 until the audit status is `"complete"`.
-
----
-
-### Step 1 — Advance the State Machine
+You are the audit-code orchestrator for this conversation. The user-facing
+surface is only `/audit-code`; do not ask the user to choose backend commands,
+providers, models, paths, or batching strategy during normal operation.
+
+Your job is to advance the deterministic state machine, delegate bounded
+semantic review when the host supports subagents, and let the backend validate
+and ingest results mechanically.
+
+## Core Guardrails
+
+- Do not edit source files during semantic review. The deterministic
+  `auto_fixes_applied` executor may run formatter/remediation commands before
+  review; that is part of the backend workflow.
+- Do not manually merge audit results, manually update coverage, or manually
+  edit audit state.
+- Do not read result schemas or completed result payloads into context unless
+  a backend command fails and the error explicitly requires diagnosis.
+- Do not inspect individual subagent result files after dispatch. Validation
+  and ingestion are backend responsibilities.
+- Prefer subagent dispatch for semantic review whenever the host exposes an
+  Agent/subagent tool.
+- If the host cannot dispatch subagents, complete exactly one assigned review
+  task, run the provided ingestion command, then stop. The user can run
+  `/audit-code` again to continue from fresh context.
+
+## Step 1 - Advance Deterministic State
 
 Run:
 
@@ -24,82 +39,97 @@ Run:
 audit-code
 ```
 
-_(Inside the `auditor-lambda` repo itself, use `node audit-code.mjs` instead.)_
+Inside the `auditor-lambda` repository itself, use:
 
-Parse the JSON output. Check `audit_state.status`:
+```bash
+node audit-code.mjs
+```
 
-| Status | Action |
-|--------|--------|
-| `"complete"` | Go to **Step 6** |
-| `"active"` | Deterministic progress was made — loop immediately back to Step 1 |
-| `"blocked"` | LLM work needed — continue to Step 2 |
+Parse only the command JSON envelope needed for routing:
 
----
+- `audit_state.status`
+- `handoff.active_review_run.run_id`
+- `handoff.artifacts_dir`
+- `handoff.active_review_run.task_path`
+- `handoff.active_review_run.prompt_path`
+- `handoff.active_review_run.pending_audit_tasks_path`
+- `handoff.active_review_run.audit_results_path`
+- `handoff.active_review_run.worker_command`
 
-### Step 2 — Extract the Task IDs
+If status is `"active"`, deterministic progress was made. Run Step 1 again.
 
-Parse these fields directly from the Step 1 JSON output:
-- `run_id` — from `handoff.active_review_run.run_id`
-- `artifacts_dir` — from `handoff.artifacts_dir`
+If status is `"complete"`, skip to Step 5.
 
-_(If `audit_state.blockers` contains a message that requires operator input rather than code review, stop and report the blocker verbatim to the user.)_
+If status is `"blocked"` and the blocker is not semantic review, report the
+blocker verbatim and stop.
 
----
+If status is `"blocked"` for semantic review, continue to Step 2.
 
-### Step 3 — Prepare the Dispatch Plan
+## Step 2 - Dispatch Review Work
 
-Run:
+When the host supports subagents, prepare a dispatch plan:
 
 ```bash
 audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
 ```
 
-Read `<artifacts_dir>/runs/<run_id>/dispatch-plan.json`. It is a JSON array where each entry has:
-- `task_id` — task identifier
-- `description` — short label for the Agent call
-- `output_path` — where the subagent writes its result
-- `prompt_path` — path to the complete subagent instructions file
+Read only `<artifacts_dir>/runs/<run_id>/dispatch-plan.json`.
 
----
+In a single message, launch one Agent/subagent call per dispatch-plan entry:
 
-### Step 4 — Dispatch All Subagents in Parallel
-
-**In a single message**, fire one `Agent` call per entry in `dispatch-plan.json`:
-
-```
+```text
 Agent({ description: entry.description, prompt: "Read and follow the audit instructions in: " + entry.prompt_path })
 ```
 
-All calls must be sent simultaneously — never await one before firing the next. This is the critical performance constraint. Wait for all to complete before proceeding.
-
-Each subagent reads its instruction file, reviews the assigned code, writes a validated JSON result to `output_path`, and self-validates. You do not need to inspect individual subagent output.
-
----
+All subagent calls should be launched together. Wait for them to finish.
 
-### Step 5 — Merge and Ingest
+Subagents own bounded semantic review. They must read only their prompt and
+assigned files, write exactly the requested audit result JSON to `output_path`,
+run the validation command in their prompt, retry up to 3 times if validation
+fails, and stop. They must not edit source files, remediate findings, create
+extra task results, run unrelated audits, or write the worker `result.json`
+control envelope.
 
-Run:
+Then run:
 
 ```bash
 audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
 ```
 
-Loop back to **Step 1**.
+If `merge-and-ingest` exits non-zero, stop immediately and report the exact
+error. Do not improvise manual merging or state edits.
 
----
+Loop back to Step 1.
 
-### Step 6 — Present Results
+## Step 3 - Single-Task Fallback
 
-When `audit_state.status` is `"complete"`, stop the loop. Do **not** run the orchestrator again.
+Use this path only when the host cannot dispatch subagents.
 
-Read `audit-report.md` and present the completed audit to the user. Lead with the work blocks — they are the primary remediation handoff.
+Read the current review prompt named by `handoff.active_review_run.prompt_path`
+or `.audit-artifacts/dispatch/current-prompt.md`, plus the matching task file
+needed to find `audit_results_path` and `worker_command`.
 
----
+Complete exactly one assigned review task. If a batch file lists multiple tasks,
+choose the first pending task only. Read only that task's assigned files. Write
+one valid `AuditResult` object, wrapped in a JSON array, to `audit_results_path`.
+
+Run the exact `worker_command` from the task file. Then stop and summarize that
+one bounded step. Do not loop into another semantic review task in the same
+conversation turn.
+
+## Step 4 - Backend Failure Handling
+
+If `prepare-dispatch`, `merge-and-ingest`, or `worker_command` fails:
 
-## Edge Cases
+- stop immediately
+- report the exact command and error output
+- do not manually create prompts, split tasks, merge results, edit state, or
+  remediate application code
 
-**Large task warnings:** `prepare-dispatch` warns about tasks exceeding ~1500 lines. If a subagent hits a quota limit and fails to produce output, `merge-and-ingest` excludes it silently — those tasks remain pending and are picked up in the next loop iteration. No manual intervention needed.
+Invalid or missing subagent output is a blocker. It should not be silently
+merged or treated as automatic progress.
 
-**Failed validation:** Subagents self-validate and retry up to 3 times before finishing. `merge-and-ingest` excludes any results that still lack required fields and writes `failed-tasks.json`. Those tasks are requeued automatically in the next cycle.
+## Step 5 - Present Results
 
-**Command failures:** If `prepare-dispatch` or `merge-and-ingest` exits non-zero, **STOP immediately** and report the exact error output to the user. Do NOT improvise manual dispatch, manually split tasks, manually create directories, manually construct prompts, or manually merge results. These scripts are the canonical mechanism — operating without them produces incorrect output. Fix the underlying issue and re-run the failed command.
+When `audit_state.status` is `"complete"`, do not run the orchestrator again.
+Read `audit-report.md` and present the completed audit with work blocks first.

package/dispatch/prepare-dispatch.mjs

@@ -1,136 +0,0 @@
-import { dirname, resolve, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const PACKAGE_ROOT = resolve(__dirname, "..");
-
-// Parse --run-id
-const runIdIdx = process.argv.indexOf("--run-id");
-if (runIdIdx === -1 || !process.argv[runIdIdx + 1]) {
-  console.error("Usage: node dispatch/prepare-dispatch.mjs --run-id <run_id> [--artifacts-dir <dir>]");
-  process.exit(1);
-}
-const run_id = process.argv[runIdIdx + 1];
-
-// Parse --artifacts-dir (default: CWD/.audit-artifacts)
-const artifactsDirIdx = process.argv.indexOf("--artifacts-dir");
-const artifactsDir = artifactsDirIdx !== -1 && process.argv[artifactsDirIdx + 1]
-  ? resolve(process.argv[artifactsDirIdx + 1])
-  : join(process.cwd(), ".audit-artifacts");
-
-const runDir = join(artifactsDir, "runs", run_id);
-const tasksPath = join(runDir, "pending-audit-tasks.json");
-const taskResultsDir = join(runDir, "task-results");
-const dispatchPlanPath = join(runDir, "dispatch-plan.json");
-
-let tasks;
-try {
-  tasks = JSON.parse(readFileSync(tasksPath, "utf8"));
-} catch (e) {
-  console.error(`Cannot read ${tasksPath}: ${e.message}`);
-  process.exit(1);
-}
-
-const lensDefinitions = JSON.parse(
-  readFileSync(join(__dirname, "lens-definitions.json"), "utf8")
-);
-
-mkdirSync(taskResultsDir, { recursive: true });
-
-function buildPrompt(task, lensDef, outputPath, runId, artifactsDir) {
-  const fileList = task.file_paths.map(p => {
-    const lines = task.file_line_counts?.[p] ?? 0;
-    return `- ${p} (${lines} lines)`;
-  }).join("\n");
-
-  return `You are a code auditor. Review the files below under the specified lens.
-
-## Task
-task_id: ${task.task_id}
-unit_id: ${task.unit_id}
-pass_id: ${task.pass_id}
-lens: ${task.lens}
-
-## Files to read
-Use your Read tool. Paths are repo-relative from the current working directory.
-${fileList}
-
-## Lens: ${task.lens}
-${lensDef?.description ?? task.lens}
-
-Do NOT report: ${lensDef?.do_not_report ?? "N/A"}
-
-## Output
-Write a single JSON object to: ${outputPath}
-
-Required fields:
-  task_id       copy from task metadata above
-  unit_id       copy from task metadata above
-  pass_id       copy from task metadata above
-  lens          copy from task metadata above
-  file_coverage [{path, total_lines}] — one entry per file; use the line counts listed above
-  findings      [] or array of finding objects (see below)
-
-Each finding object (omit optional fields if not applicable):
-  id            unique ID, e.g. "SEC-001"
-  title         short title
-  category      correctness|architecture|maintainability|security|reliability|performance|data_integrity|tests|operability|config_deployment
-  severity      critical|high|medium|low|info
-  confidence    high|medium|low
-  lens          "${task.lens}" — must match task lens exactly
-  summary       1–2 sentence description
-  affected_files  [{path, line_start?, line_end?, symbol?}] — objects, not strings; min 1 entry
-  evidence     ["path/to/file.ts:42 — description of what you see there"] — min 1 entry
-
-Constraints:
-1. line_end must not exceed the file's actual line count (use the counts listed above)
-2. affected_files entries are OBJECTS with a "path" key — NOT plain strings
-3. Only reference files from the list above
-4. findings: [] is correct when you find nothing genuine — do not invent findings
-
-## Validate
-After writing your result, run:
-  audit-code validate-result --run-id ${runId} --task-id ${task.task_id} --artifacts-dir ${artifactsDir}
-
-Exit 0 means valid. Non-zero: read the errors, fix your JSON, rewrite the file, run again. Retry up to 3 times.`;
-}
-
-const plan = [];
-let largestTask = null;
-let largestLines = 0;
-
-for (const task of tasks) {
-  const sanitizedId = task.task_id.replace(/[^a-zA-Z0-9_-]/g, "_");
-  const outputPath = join(taskResultsDir, sanitizedId + ".json");
-  const promptPath = join(taskResultsDir, sanitizedId + ".prompt.md");
-  const lensDef = lensDefinitions[task.lens];
-
-  if (!lensDef) {
-    process.stderr.write(`Warning: no lens definition for '${task.lens}' (task ${task.task_id})\n`);
-  }
-
-  const totalFileLines = Object.values(task.file_line_counts ?? {}).reduce((a, b) => a + b, 0);
-
-  if (totalFileLines > largestLines) {
-    largestLines = totalFileLines;
-    largestTask = task.task_id;
-  }
-  if (totalFileLines > 1500) {
-    process.stderr.write(`Warning: large task ${task.task_id} (~${totalFileLines} lines) may hit quota limits\n`);
-  }
-
-  const prompt = buildPrompt(task, lensDef, outputPath, run_id, artifactsDir);
-  writeFileSync(promptPath, prompt, "utf8");
-
-  const description = `Audit ${task.unit_id} (${task.file_paths.length} file(s), ~${totalFileLines} lines) — ${task.lens} lens`;
-  plan.push({ task_id: task.task_id, description, output_path: outputPath, prompt_path: promptPath });
-}
-
-writeFileSync(dispatchPlanPath, JSON.stringify(plan, null, 2));
-
-console.log(`Wrote dispatch-plan.json — ${plan.length} tasks ready for dispatch`);
-if (largestTask) {
-  console.log(`Largest task: ${largestTask} (~${largestLines} lines)`);
-}