auditor-lambda 0.2.18 → 0.3.0

package/dispatch/merge-results.mjs

@@ -5,17 +5,21 @@ import { validateResult } from "./validate.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const PROJECT_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/merge-results.mjs --run-id <run_id>");
+  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 artifactsDir = join(PROJECT_ROOT, ".audit-artifacts");
+// 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");
@@ -69,9 +73,9 @@ writeFileSync(auditResultsPath, JSON.stringify(passing, null, 2));
 
 if (failing.length > 0) {
   writeFileSync(failedTasksPath, JSON.stringify(failing, null, 2));
-  console.warn(`${failing.length} task(s) failed validation and were excluded:`);
+  process.stderr.write(`${failing.length} task(s) failed validation and were excluded:\n`);
   for (const f of failing) {
-    console.warn(`  ✗ ${f.task_id}: ${f.errors[0]}`);
+    process.stderr.write(`  ✗ ${f.task_id}: ${f.errors[0]}\n`);
   }
 }
 

package/dispatch/prepare-dispatch.mjs

@@ -1,143 +1,131 @@
 import { dirname, resolve, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const PROJECT_ROOT = resolve(__dirname, "..");
+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>");
+  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];
 
-const artifactsDir = join(PROJECT_ROOT, ".audit-artifacts");
+// 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");
 
-if (!existsSync(tasksPath)) {
-  console.error(`File not found: ${tasksPath}`);
+let tasks;
+try {
+  tasks = JSON.parse(readFileSync(tasksPath, "utf8"));
+} catch (e) {
+  console.error(`Cannot read ${tasksPath}: ${e.message}`);
   process.exit(1);
 }
 
-const tasks = JSON.parse(readFileSync(tasksPath, "utf8"));
 const lensDefinitions = JSON.parse(
   readFileSync(join(__dirname, "lens-definitions.json"), "utf8")
 );
-const auditResultSchema = JSON.parse(
-  readFileSync(join(PROJECT_ROOT, "schemas", "audit_result.schema.json"), "utf8")
-);
-const findingSchema = JSON.parse(
-  readFileSync(join(PROJECT_ROOT, "schemas", "finding.schema.json"), "utf8")
-);
 
-function buildPrompt(task, lensDef, auditResultSchema, findingSchema, outputPath, runId, artifactsDir) {
-  const fallback = {
-    task_id: task.task_id,
-    unit_id: task.unit_id,
-    pass_id: task.pass_id,
-    lens: task.lens,
-    file_coverage: task.file_paths.map(p => ({ path: p, total_lines: task.file_line_counts[p] })),
-    findings: [],
-    notes: ["Validation failed after 3 attempts — empty result written as fallback."]
-  };
+mkdirSync(taskResultsDir, { recursive: true });
 
-  return `You are a code auditor. Perform a bounded audit of the files listed below under the specified lens.
+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");
 
-## Task metadata
-${JSON.stringify(task, null, 2)}
+  return `You are a code auditor. Review the files below under the specified lens.
 
-## Files to read
-Read each path in task.file_paths using your Read tool. The repo root is the current working directory — paths are repo-relative (e.g. "src/foo.ts").
+## Task
+task_id: ${task.task_id}
+unit_id: ${task.unit_id}
+pass_id: ${task.pass_id}
+lens: ${task.lens}
 
-file_line_counts gives the expected total line count for each file. Use those exact values for file_coverage[].total_lines in your result.
+## Files to read
+Use your Read tool. Paths are repo-relative from the current working directory.
+${fileList}
 
 ## Lens: ${task.lens}
-${lensDef.description}
-
-Do NOT report: ${lensDef.do_not_report}
-
-## Output format
-Write your result as a single JSON **object** (not an array) to this exact path:
-  ${outputPath}
-
-The result must conform to the following schema:
-
-### audit_result.schema.json
-${JSON.stringify(auditResultSchema, null, 2)}
-
-### finding.schema.json
-${JSON.stringify(findingSchema, null, 2)}
-
-## Hard constraints (violations will fail validation)
-1. NEVER set line_end higher than the file's actual line count.
-   Use file_line_counts as your reference. If in doubt, leave line_end omitted.
-2. Every finding MUST have ALL required fields:
-   id, title, category, severity, confidence, lens, summary, affected_files, evidence
-3. lens on every finding must be exactly "${task.lens}"
-4. No fields outside the schema. Forbidden: "recommendation", "tags", "description" (use "summary").
-5. evidence[] must contain at least one specific file:line reference.
-   Format: "path/to/file.ts:42 - brief description of what you see there"
-6. affected_files[] entries are OBJECTS with a "path" key — NOT plain strings.
-   Example: {"path": "src/foo.ts", "line_start": 10, "line_end": 20, "symbol": "myFunc"}
-7. Only reference file paths that appear in this task's file_paths.
-8. findings: [] is correct when you genuinely find nothing. Do not invent findings.
-
-## Validation step (required)
+${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:
-  node dispatch/validate-result.mjs ${runId} ${task.task_id}
-
-- If it exits 0: you are done. Stop.
-- If it exits non-zero: read the error output, fix the JSON, rewrite the file, run again.
-- Repeat up to 3 times.
+  audit-code validate-result --run-id ${runId} --task-id ${task.task_id} --artifacts-dir ${artifactsDir}
 
-If you cannot produce a valid result after 3 attempts, write this fallback (substituting real values):
-${JSON.stringify(fallback, null, 2)}
-
-Then validate the fallback passes before finishing.`;
+Exit 0 means valid. Non-zero: read the errors, fix your JSON, rewrite the file, run again. Retry up to 3 times.`;
 }
 
-mkdirSync(join(runDir, "task-results"), { recursive: true });
-
 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(runDir, "task-results", sanitizedId + ".json");
+  const outputPath = join(taskResultsDir, sanitizedId + ".json");
+  const promptPath = join(taskResultsDir, sanitizedId + ".prompt.md");
   const lensDef = lensDefinitions[task.lens];
 
   if (!lensDef) {
-    console.warn(`Warning: no lens definition for '${task.lens}' (task ${task.task_id})`);
+    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);
-  const description = `Audit ${task.unit_id} (${task.file_paths.length} file(s), ~${totalFileLines} lines) — ${task.lens} lens`;
-  const prompt = buildPrompt(
-    task,
-    lensDef ?? { description: task.lens, do_not_report: "N/A" },
-    auditResultSchema,
-    findingSchema,
-    outputPath,
-    run_id,
-    artifactsDir
-  );
+  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) {
-    console.warn(`Warning: large task ${task.task_id} (~${totalFileLines} lines) may hit quota limits`);
+    process.stderr.write(`Warning: large task ${task.task_id} (~${totalFileLines} lines) may hit quota limits\n`);
   }
 
-  plan.push({ task_id: task.task_id, description, output_path: outputPath, prompt });
+  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));
@@ -146,10 +134,3 @@ console.log(`Wrote dispatch-plan.json — ${plan.length} tasks ready for dispatc
 if (largestTask) {
   console.log(`Largest task: ${largestTask} (~${largestLines} lines)`);
 }
-console.log("");
-console.log("--- ORCHESTRATOR INSTRUCTIONS ---");
-console.log("Read dispatch-plan.json. For each entry, fire one Agent call with:");
-console.log("  description: <entry.description>");
-console.log("  prompt: <entry.prompt>");
-console.log(`Fire all ${plan.length} calls in a single message for parallel execution.`);
-console.log(`When all complete, run: node dispatch/merge-results.mjs --run-id ${run_id}`);

package/dispatch/validate-result.mjs

@@ -5,27 +5,31 @@ import { validateResult } from "./validate.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const PROJECT_ROOT = resolve(__dirname, "..");
 
-const run_id = process.argv[2];
-const task_id = process.argv[3];
+// 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 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];
 
 if (!run_id || !task_id) {
-  console.error("Usage: node dispatch/validate-result.mjs <run_id> <task_id>");
+  console.error("Usage: node dispatch/validate-result.mjs --run-id <run_id> --task-id <task_id> [--artifacts-dir <dir>]");
   process.exit(1);
 }
 
-// Locate artifacts_dir
-let artifactsDir = join(PROJECT_ROOT, ".audit-artifacts");
-const sessionConfigPath = join(artifactsDir, "session-config.json");
-if (existsSync(sessionConfigPath)) {
-  try {
-    const cfg = JSON.parse(readFileSync(sessionConfigPath, "utf8"));
-    if (cfg.artifacts_dir) artifactsDir = cfg.artifacts_dir;
-  } catch {
-    // use default
-  }
-}
+// 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");

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readdir, rename } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -28,6 +28,7 @@ import { clearDispatchFiles, buildRunId, ensureSupervisorDirs, getRunPaths, writ
 import { renderWorkerPrompt } from "./prompts/renderWorkerPrompt.js";
 import { LOCAL_SUBPROCESS_PROVIDER_NAME } from "./providers/constants.js";
 import { runAuditCodeMcpServer } from "./mcp/server.js";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const ADVANCE_AUDIT_CONTRACT_VERSION = "audit-code/v1alpha1";
 const WORKER_RESULT_CONTRACT_VERSION = "audit-code-worker-result/v1alpha1";
 const DIRECT_CLI_DEFAULTS = {
@@ -170,8 +171,9 @@ async function emitEnvelope(params) {
 }
 function buildManualReviewBlocker(providerName) {
     return providerName === LOCAL_SUBPROCESS_PROVIDER_NAME
-        ? "Automatic backend steps are exhausted. Remaining semantic review now belongs to the active conversation agent. Review the dispatched files, write structured audit results to the run-scoped audit_results_path, and execute the worker_command from current-task.json exactly as written. If you intentionally want a backend bridge instead, re-run audit-code with --provider auto, --provider claude-code, --provider opencode, --provider subprocess-template, or --provider vscode-task."
-        : "Automatic work is exhausted. Remaining audit tasks require explicit audit results or an interactive provider.";
+        ? "Ready for LLM review. Dispatched task files are in .audit-artifacts/dispatch/. " +
+            "Review the code, write audit results to the specified path, then run the worker_command to continue."
+        : "Audit blocked: waiting for manual audit results or interactive provider configuration.";
 }
 function shouldRunInlineExecutor(selectedExecutor) {
     return selectedExecutor !== null && selectedExecutor !== "agent";
@@ -1393,6 +1395,284 @@ async function cmdWorkerRun(argv) {
         process.exitCode = 1;
     }
 }
+async function cmdPrepareDispatch(argv) {
+    const runId = getFlag(argv, "--run-id");
+    if (!runId)
+        throw new Error("prepare-dispatch requires --run-id <run_id>");
+    const artifactsDir = getArtifactsDir(argv);
+    const runDir = join(artifactsDir, "runs", runId);
+    const tasksPath = join(runDir, "pending-audit-tasks.json");
+    const taskResultsDir = join(runDir, "task-results");
+    const dispatchPlanPath = join(runDir, "dispatch-plan.json");
+    const tasks = await readJsonFile(tasksPath);
+    const lensDefsPath = join(packageRoot, "dispatch", "lens-definitions.json");
+    const lensDefs = await readJsonFile(lensDefsPath);
+    await mkdir(taskResultsDir, { recursive: true });
+    const plan = [];
+    let largestTask = null;
+    let largestLines = 0;
+    for (const task of tasks) {
+        const sanitized = task.task_id.replace(/[^a-zA-Z0-9_-]/g, "_");
+        const outputPath = join(taskResultsDir, `${sanitized}.json`);
+        const promptPath = join(taskResultsDir, `${sanitized}.prompt.md`);
+        const lensDef = lensDefs[task.lens];
+        if (!lensDef) {
+            process.stderr.write(`Warning: no lens definition for '${task.lens}' (task ${task.task_id})\n`);
+        }
+        const totalLines = Object.values(task.file_line_counts ?? {}).reduce((a, b) => a + b, 0);
+        if (totalLines > largestLines) {
+            largestLines = totalLines;
+            largestTask = task.task_id;
+        }
+        if (totalLines > 1500) {
+            process.stderr.write(`Warning: large task ${task.task_id} (~${totalLines} lines) may hit quota limits\n`);
+        }
+        const fileList = task.file_paths.map(p => {
+            const lines = task.file_line_counts?.[p] ?? 0;
+            return `- ${p} (${lines} lines)`;
+        }).join("\n");
+        const prompt = [
+            "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:",
+            "  id            unique ID, e.g. \"COR-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 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",
+            "",
+            "## 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.",
+        ].join("\n");
+        await writeFile(promptPath, prompt, "utf8");
+        const description = `Audit ${task.unit_id} (${task.file_paths.length} file(s), ~${totalLines} lines) — ${task.lens} lens`;
+        plan.push({ task_id: task.task_id, description, output_path: outputPath, prompt_path: promptPath });
+    }
+    await writeJsonFile(dispatchPlanPath, plan);
+    console.log(`Wrote dispatch-plan.json — ${plan.length} tasks ready for dispatch`);
+    if (largestTask)
+        console.log(`Largest task: ${largestTask} (~${largestLines} lines)`);
+}
+async function cmdMergeAndIngest(argv) {
+    const runId = getFlag(argv, "--run-id");
+    if (!runId)
+        throw new Error("merge-and-ingest requires --run-id <run_id>");
+    const artifactsDir = getArtifactsDir(argv);
+    const runDir = join(artifactsDir, "runs", runId);
+    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)
+    let files;
+    try {
+        files = (await readdir(taskResultsDir))
+            .filter(f => f.endsWith(".json"))
+            .sort();
+    }
+    catch {
+        files = [];
+    }
+    const passing = [];
+    const failing = [];
+    for (const filename of files) {
+        const filePath = join(taskResultsDir, filename);
+        let obj;
+        try {
+            obj = JSON.parse(await readFile(filePath, "utf8"));
+        }
+        catch (e) {
+            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(", ")}`] });
+        }
+        else {
+            passing.push(obj);
+        }
+    }
+    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`);
+    }
+    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");
+    if (!runId || !taskId)
+        throw new Error("validate-result requires --run-id and --task-id");
+    const artifactsDir = getArtifactsDir(argv);
+    const sanitized = taskId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    const resultPath = join(artifactsDir, "runs", runId, "task-results", `${sanitized}.json`);
+    const tasksPath = join(artifactsDir, "runs", runId, "pending-audit-tasks.json");
+    let raw;
+    try {
+        raw = await readFile(resultPath, "utf8");
+    }
+    catch {
+        console.error(`File not found: ${resultPath}`);
+        process.exitCode = 1;
+        return;
+    }
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch (e) {
+        console.error(`Invalid JSON: ${e.message}`);
+        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 = {};
+    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}`);
+                }
+            }
+        }
+    }
+    if (errors.length === 0) {
+        console.log(`✓ valid: ${taskId}`);
+    }
+    else {
+        console.error(`✗ invalid: ${taskId}`);
+        for (const e of errors)
+            console.error(`  ${e}`);
+        process.exitCode = 1;
+    }
+}
 async function cmdImportExternalAnalyzer(argv) {
     const artifactsDir = getArtifactsDir(argv);
     const sourcePath = getFlag(argv, "--external-analyzer-results", `${artifactsDir}/external_analyzer_results.json`);
@@ -1641,9 +1921,18 @@ async function main(argv) {
         case "mcp":
             await cmdMcp(argv);
             return;
+        case "prepare-dispatch":
+            await cmdPrepareDispatch(argv);
+            return;
+        case "merge-and-ingest":
+            await cmdMergeAndIngest(argv);
+            return;
+        case "validate-result":
+            await cmdValidateResult(argv);
+            return;
         default:
             console.error(`Unknown command: ${command}`);
-            console.error("Available commands: sample-run, advance-audit, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, mcp");
+            console.error("Available commands: sample-run, advance-audit, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, mcp, prepare-dispatch, merge-and-ingest, validate-result");
             process.exitCode = 1;
     }
 }

package/dist/prompts/renderWorkerPrompt.js

@@ -8,60 +8,28 @@ export function renderWorkerPrompt(task) {
         const tasksPath = task.pending_audit_tasks_path ??
             `${task.artifacts_dir}/audit_tasks.json`;
         const lines = [
-            "You are executing one bounded audit run for audit-code.",
-            `Run ID: ${task.run_id}`,
-            `Repository root: ${task.repo_root}`,
-            "",
-            `Read the task file: ${tasksPath}`,
-            "It contains the task(s) assigned to this run.",
-            "",
-            "For each task:",
-            "  1. Read every file listed in file_paths in full using your file-reading tool.",
-            "     If line_ranges are present, they are a focus hint — still read the whole file.",
-            "  2. Review the content under the specified lens.",
-            "  3. Emit one AuditResult with:",
-            "       task_id, unit_id, pass_id, lens",
-            "       file_coverage: [{path, total_lines}] for every assigned file you reviewed",
-            "       findings: array (empty if nothing found)",
-            "     If the task includes file_line_counts, use those values for file_coverage.total_lines.",
-            "     total_lines must match the file's current total line count.",
-            "     Each finding must include:",
-            "       id, title, category, severity, confidence, lens, summary",
-            "       affected_files: [{path, line_start?, line_end?, symbol?}] — path is repo-relative, NOT a plain string",
-            "       evidence: array of plain strings only, at least one excerpt or line reference from the file you read",
-            "       Example evidence entry: src/foo.ts:42 - variable overwritten before use",
-            "       Example affected_files entry: {\"path\": \"src/foo.ts\", \"line_start\": 42, \"line_end\": 55, \"symbol\": \"myFunction\"}",
-            "     Optional finding fields: impact, likelihood, reproduction, systemic, related_findings",
-            "     Low-priority tasks still require a real review. Use findings: [] only when you genuinely found nothing notable.",
-            task.timeout_ms
-                ? `     Time budget for this task: ${task.timeout_ms} ms.`
-                : "     Keep the task bounded to the assigned files only.",
-            `Reference schemas: ${task.artifacts_dir}/dispatch/audit-result.schema.json and ${task.artifacts_dir}/dispatch/finding.schema.json`,
-            `Write the AuditResult[] JSON array to: ${task.audit_results_path}`,
+            `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: task_id, unit_id, pass_id, lens, file_coverage,",
+            "findings. Each finding: id, title, category, severity, confidence, lens, summary,",
+            "affected_files (path, line_start, line_end, symbol), evidence (plain strings).",
+            `Write to: ${task.audit_results_path}`,
         ];
         if (usesDeferredWorkerCommand(task)) {
-            lines.push("", "This run is using deferred worker-command ingestion.", "Do not execute worker_command in this session.", "Stop after writing the results file.");
+            lines.push("Deferred mode: write results, do not execute worker_command.");
         }
         else {
-            lines.push("", "Then execute the worker_command array from task.json exactly as written.", "Preserve argv boundaries instead of reconstructing shell quoting.", `worker_command argv JSON: ${commandArgv}`, "Stop after the command completes.");
+            lines.push("Then execute worker_command from task.json exactly.", `Command: ${commandArgv}`);
         }
         return lines.join("\n");
     }
     return [
-        "You are executing one bounded audit step for audit-code.",
-        `Run ID: ${task.run_id}`,
-        `Repository root: ${task.repo_root}`,
-        `Obligation: ${task.obligation_id ?? "unknown"}`,
+        `Task: ${task.run_id}`,
         `Executor: ${task.preferred_executor}`,
-        "Execute the worker_command array from task.json exactly as written.",
-        "Preserve argv boundaries instead of reconstructing shell quoting.",
-        `worker_command argv JSON: ${commandArgv}`,
-        "Do not continue the audit recursively.",
-        "Do not choose another task.",
-        task.timeout_ms
-            ? `The worker command is budgeted for ${task.timeout_ms} ms.`
-            : "If the command hangs or fails, stop and let the supervisor handle it.",
-        `The command must write the worker result JSON to: ${task.result_path}`,
-        "After the command completes, stop.",
+        "Execute worker_command from task.json exactly.",
+        `Command: ${commandArgv}`,
+        "Write result to: " + task.result_path,
+        "Stop after completion.",
     ].join("\n");
 }

package/dist/providers/index.js

@@ -29,6 +29,14 @@ export function resolveFreshSessionProviderName(name, sessionConfig = {}, option
     const lookupCommand = options.commandExists ?? commandExists;
     const inVSCode = (env.TERM_PROGRAM ?? "").toLowerCase() === "vscode";
     const insideClaudeCode = Boolean(env.CLAUDECODE);
+    const insideOpenCode = Boolean(env.OPENCODE);
+    // If we're inside a specific IDE/conversation, use that as the provider
+    if (insideOpenCode) {
+        return "opencode";
+    }
+    if (insideClaudeCode) {
+        return "claude-code";
+    }
     if (inVSCode && hasEntries(sessionConfig.vscode_task?.command_template)) {
         return "vscode-task";
     }

package/dist/supervisor/operatorHandoff.d.ts

@@ -38,6 +38,8 @@ export interface AuditCodeHandoff {
     interactive_provider_hint: string | null;
     artifact_paths: AuditCodeHandoffArtifactPaths;
     active_review_run?: ActiveReviewRun;
+    quick_start?: string;
+    file_map?: Record<string, string>;
 }
 export declare function buildAuditCodeHandoff(params: {
     root: string;

package/dist/supervisor/operatorHandoff.js

@@ -115,10 +115,10 @@ function buildInteractiveProviderHint(status, providerName, sessionConfigPath, i
         return null;
     }
     if (isConfigError) {
-        return `A project configuration issue is blocking the audit. Verify that --root points to the repository root containing a project file (package.json, go.mod, etc.), then run audit-code again.`;
+        return `Configuration error: Verify --root points to a repository root (with package.json, go.mod, etc.).`;
     }
     const providerLabel = providerName ?? LOCAL_SUBPROCESS_PROVIDER_NAME;
-    return `Current backend worker provider is ${providerLabel}. Remaining semantic review belongs to the active conversation agent by default. If you intentionally want the backend to continue through a compatibility bridge instead, configure ${sessionConfigPath} for ${formatQuotedList(INTERACTIVE_PROVIDER_OPTIONS)} and re-run audit-code with an explicit --provider value from the repository root.`;
+    return `Provider: ${providerLabel}. For automatic LLM review, configure an interactive provider in ${sessionConfigPath}.`;
 }
 function renderMarkdown(handoff) {
     const lines = [
@@ -208,7 +208,7 @@ export function buildAuditCodeHandoff(params) {
             : null,
     };
     const suggestedInputs = buildSuggestedInputs(params.artifactsDir, params.state.status, isConfigError, params.activeReviewRun);
-    return {
+    const handoff = {
         status: params.state.status,
         repo_root: params.root,
         artifacts_dir: params.artifactsDir,
@@ -221,6 +221,17 @@ export function buildAuditCodeHandoff(params) {
         artifact_paths: artifactPaths,
         active_review_run: params.activeReviewRun,
     };
+    // Add quick_start command and file map when blocked for review
+    if (params.state.status === BLOCKED_STATUS && params.activeReviewRun) {
+        handoff.quick_start = `audit-code worker-run --task ${params.activeReviewRun.task_path}`;
+        handoff.file_map = {
+            current_task: artifactPaths.current_task,
+            current_prompt: artifactPaths.current_prompt,
+            audit_results: params.activeReviewRun.audit_results_path,
+            final_report: join(params.root, "audit-report.md"),
+        };
+    }
+    return handoff;
 }
 export async function writeAuditCodeHandoffArtifacts(handoff) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.2.18",
+  "version": "0.3.0",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",

package/schemas/audit-code-v1alpha1.schema.json

@@ -236,6 +236,15 @@
               "type": ["string", "null"]
             }
           }
+        },
+        "quick_start": {
+          "type": "string"
+        },
+        "file_map": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
         }
       }
     }

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

@@ -21,10 +21,10 @@ Repeat Steps 1–5 until the audit status is `"complete"`.
 Run:
 
 ```bash
-node audit-code.mjs
+audit-code
 ```
 
-_(Outside the `auditor-lambda` repo itself, use `audit-code` or `npx audit-code` instead.)_
+_(Inside the `auditor-lambda` repo itself, use `node audit-code.mjs` instead.)_
 
 Parse the JSON output. Check `audit_state.status`:
 
@@ -38,13 +38,13 @@ Parse the JSON output. Check `audit_state.status`:
 
 ### Step 2 — Read the Task
 
-Read `.audit-artifacts/dispatch/current-task.json`.
+Read the file at `.audit-artifacts/dispatch/current-task.json`.
 
 Note these fields:
 - `run_id` — identifies this batch of audit work
 - `artifacts_dir` — base artifacts directory
-- `pending_audit_tasks_path` — path to the pending task list
-- `worker_command` — JSON array; run this after the audit work is complete
+
+_(If `audit_state.blockers` contains a message that requires operator input rather than code review, stop and report the blocker verbatim to the user.)_
 
 ---
 
@@ -53,16 +53,14 @@ Note these fields:
 Run:
 
 ```bash
-node dispatch/prepare-dispatch.mjs --run-id <run_id>
+audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
 ```
 
-This reads every pending audit task, pre-computes a complete subagent prompt for each, and writes `dispatch-plan.json` to the same directory as `pending_audit_tasks_path`. It prints the task count and warns about any tasks exceeding 1500 lines.
-
-Read `dispatch-plan.json`. It is a JSON array where each entry has:
+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` — the complete, ready-to-use subagent prompt (do not modify it)
+- `prompt_path` — path to the complete subagent instructions file
 
 ---
 
@@ -71,25 +69,23 @@ Read `dispatch-plan.json`. It is a JSON array where each entry has:
 **In a single message**, fire one `Agent` call per entry in `dispatch-plan.json`:
 
 ```
-Agent({ description: entry.description, prompt: entry.prompt })
+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 assigned files, writes a validated JSON result to `output_path`, and self-validates via `node dispatch/validate-result.mjs`. You do not need to check individual subagent output.
+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.
 
 ---
 
 ### Step 5 — Merge and Ingest
 
-Run in sequence:
+Run:
 
 ```bash
-node dispatch/merge-results.mjs --run-id <run_id>
+audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
 ```
 
-Then execute the `worker_command` from `current-task.json`. It is a JSON array — join the elements into a shell command and run it.
-
 Loop back to **Step 1**.
 
 ---
@@ -98,14 +94,12 @@ Loop back to **Step 1**.
 
 When `audit_state.status` is `"complete"`, stop the loop. Do **not** run the orchestrator again.
 
-Read `audit-report.md` and present the completed audit to the user. Lead with the work blocks — they are the primary remediation handoff. Wait for the user to ask you to begin resolving one or more work blocks.
+Read `audit-report.md` and present the completed audit to the user. Lead with the work blocks — they are the primary remediation handoff.
 
 ---
 
 ## Edge Cases
 
-**Non-agent blocker:** If `audit_state.blockers` contains a message that requires operator input (not code review), stop and report the blocker verbatim to the user.
-
-**Large task warnings:** `prepare-dispatch.mjs` warns about tasks exceeding ~1500 lines. If a subagent hits a quota limit and fails to produce output, `merge-results.mjs` excludes it silently — those tasks remain pending and are picked up in the next loop iteration. No manual intervention needed.
+**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.
 
-**Failed validation:** Subagents self-validate and retry up to 3 times before writing a fallback empty result. `merge-results.mjs` writes `failed-tasks.json` listing any tasks that still failed. Those tasks are requeued automatically in the next cycle.
+**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.