auditor-lambda 0.2.15 → 0.2.17

package/dispatch/lens-definitions.json

@@ -0,0 +1,38 @@
+{
+  "correctness": {
+    "description": "Logic errors, incorrect algorithm implementations, off-by-one bugs, type mismatches, wrong return values, incorrect state transitions, missing null/undefined guards, misuse of APIs. Focus on code that does the wrong thing.",
+    "do_not_report": "Style issues, naming problems, missing tests, or findings that belong to other lenses."
+  },
+  "maintainability": {
+    "description": "Code that is hard to change safely: excessive function length, deep nesting, tight coupling between unrelated modules, poor naming, magic constants, duplicated logic, inconsistent abstractions, unclear public APIs.",
+    "do_not_report": "Correctness bugs, test gaps, or operational concerns."
+  },
+  "tests": {
+    "description": "Test coverage gaps for important paths, tests that assert incorrect behavior (pinning bugs as expected), fragile or non-deterministic tests, missing negative/edge-case tests, tests that silently pass on stale builds (e.g. importing compiled dist/ rather than source).",
+    "do_not_report": "Source code bugs — report only issues with the tests themselves."
+  },
+  "security": {
+    "description": "Injection vulnerabilities (SQL, shell, path traversal), authentication/authorization flaws, secret exposure, insecure deserialization, privilege escalation, unsafe use of eval or child processes with user input.",
+    "do_not_report": "Performance or correctness issues that are not security-relevant."
+  },
+  "reliability": {
+    "description": "Failure modes without recovery, missing timeouts, unhandled promise rejections, race conditions, resource leaks (file handles, sockets, timers), incorrect retry logic, cascading failure risks.",
+    "do_not_report": "Correctness bugs that do not affect reliability under failure conditions."
+  },
+  "performance": {
+    "description": "Algorithmic inefficiencies (O(n²) where O(n) is possible), unnecessary re-computation, missing caching, synchronous blocking in hot paths, excessive memory allocation.",
+    "do_not_report": "Correctness bugs unrelated to performance."
+  },
+  "data_integrity": {
+    "description": "Missing input validation at trust boundaries, schema violations, inconsistent field naming across related schemas, data loss scenarios, missing required fields, enum values that are present in some schemas but not others.",
+    "do_not_report": "UI or presentation issues; operational or deployment concerns."
+  },
+  "operability": {
+    "description": "Missing or low-quality log output, error messages that don't help operators diagnose problems, missing progress indicators for long operations, no elapsed-time reporting, lack of dry-run or preview modes for destructive operations.",
+    "do_not_report": "Correctness bugs or deployment configuration."
+  },
+  "config_deployment": {
+    "description": "CI/CD pipeline correctness (wrong triggers, missing branch filters, floating version pins), deployment safety (no gate before publish, missing rollback), insecure secret handling in configs, mutable action tags that should be pinned to commit SHAs.",
+    "do_not_report": "Runtime code issues; findings that belong to other lenses."
+  }
+}

package/dispatch/merge-results.mjs

@@ -0,0 +1,84 @@
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
+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>");
+  process.exit(1);
+}
+const run_id = process.argv[runIdIdx + 1];
+
+const artifactsDir = join(PROJECT_ROOT, ".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");
+
+// Build fileLineCounts map
+const lineCounts = {};
+if (existsSync(tasksPath)) {
+  try {
+    const tasks = JSON.parse(readFileSync(tasksPath, "utf8"));
+    for (const task of tasks) {
+      lineCounts[task.task_id] = task.file_line_counts;
+    }
+  } catch {
+    // proceed with empty map
+  }
+}
+
+if (!existsSync(taskResultsDir)) {
+  console.error(`task-results directory not found: ${taskResultsDir}`);
+  process.exit(1);
+}
+
+const files = readdirSync(taskResultsDir).filter(f => f.endsWith(".json"));
+
+const passing = [];
+const failing = [];
+
+for (const filename of files) {
+  const filePath = join(taskResultsDir, filename);
+  let resultObj;
+  try {
+    resultObj = JSON.parse(readFileSync(filePath, "utf8"));
+  } catch (e) {
+    failing.push({ task_id: filename, errors: [`Invalid JSON: ${e.message}`] });
+    continue;
+  }
+
+  const taskId = resultObj?.task_id;
+  const fileLineCounts = (taskId && lineCounts[taskId]) ? lineCounts[taskId] : {};
+  const { valid, errors } = validateResult(resultObj, fileLineCounts);
+
+  if (valid) {
+    passing.push(resultObj);
+  } else {
+    failing.push({ task_id: taskId ?? filename, errors });
+  }
+}
+
+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:`);
+  for (const f of failing) {
+    console.warn(`  ✗ ${f.task_id}: ${f.errors[0]}`);
+  }
+}
+
+const total = files.length;
+console.log(`✓ ${passing.length}/${total} tasks valid → ${auditResultsPath}`);
+if (failing.length > 0) {
+  console.log("  Re-run those tasks in the next cycle.");
+}
+
+process.exit(0);

package/dispatch/prepare-dispatch.mjs

@@ -0,0 +1,155 @@
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+
+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/prepare-dispatch.mjs --run-id <run_id>");
+  process.exit(1);
+}
+const run_id = process.argv[runIdIdx + 1];
+
+const artifactsDir = join(PROJECT_ROOT, ".audit-artifacts");
+const runDir = join(artifactsDir, "runs", run_id);
+const tasksPath = join(runDir, "pending-audit-tasks.json");
+const dispatchPlanPath = join(runDir, "dispatch-plan.json");
+
+if (!existsSync(tasksPath)) {
+  console.error(`File not found: ${tasksPath}`);
+  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."]
+  };
+
+  return `You are a code auditor. Perform a bounded audit of the files listed below under the specified lens.
+
+## Task metadata
+${JSON.stringify(task, null, 2)}
+
+## 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").
+
+file_line_counts gives the expected total line count for each file. Use those exact values for file_coverage[].total_lines in your result.
+
+## 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)
+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.
+
+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.`;
+}
+
+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 lensDef = lensDefinitions[task.lens];
+
+  if (!lensDef) {
+    console.warn(`Warning: no lens definition for '${task.lens}' (task ${task.task_id})`);
+  }
+
+  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
+  );
+
+  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`);
+  }
+
+  plan.push({ task_id: task.task_id, description, output_path: outputPath, prompt });
+}
+
+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)`);
+}
+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

@@ -0,0 +1,67 @@
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync, existsSync } from "node:fs";
+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];
+
+if (!run_id || !task_id) {
+  console.error("Usage: node dispatch/validate-result.mjs <run_id> <task_id>");
+  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
+  }
+}
+
+const sanitized = task_id.replace(/[^a-zA-Z0-9_-]/g, "_");
+const resultPath = join(artifactsDir, "runs", run_id, "task-results", sanitized + ".json");
+
+if (!existsSync(resultPath)) {
+  console.error(`File not found: ${resultPath}`);
+  process.exit(1);
+}
+
+let resultObj;
+try {
+  resultObj = JSON.parse(readFileSync(resultPath, "utf8"));
+} catch (e) {
+  console.error(`Invalid JSON in ${resultPath}: ${e.message}`);
+  process.exit(1);
+}
+
+const tasksPath = join(artifactsDir, "runs", run_id, "pending-audit-tasks.json");
+let fileLineCounts = {};
+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 ?? {};
+  } catch {
+    // use empty
+  }
+}
+
+const { valid, errors } = validateResult(resultObj, fileLineCounts);
+
+if (valid) {
+  console.log("✓ valid:", task_id);
+  process.exit(0);
+} else {
+  console.error("✗ invalid:", task_id);
+  console.error(JSON.stringify(errors, null, 2));
+  process.exit(1);
+}

package/dispatch/validate.mjs

@@ -0,0 +1,88 @@
+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) + ")" : ""}`;
+}
+
+/**
+ * @param {object} resultObj  — parsed JSON from a task-results file
+ * @param {Record<string, number>} fileLineCounts — from the task's file_line_counts
+ * @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: [] };
+}

package/docs/dispatch-implementation-plan.md

@@ -0,0 +1,553 @@
+# Dispatch Automation Implementation Plan
+
+## Background
+
+The current audit-code workflow requires the LLM orchestrator to manually assemble
+subagent prompts, handle schema normalization, and merge results — costing hundreds of
+tokens per task and producing frequent schema violations. This plan replaces that with a
+deterministic scripted dispatch layer so the orchestrator's only job is to fire Agent
+tool calls with pre-built prompts, then run a merge script.
+
+**Environment constraint:** Claude Desktop with no separate Anthropic API key. Subagent
+dispatch must go through the `Agent` tool in the conversation runtime — no direct SDK
+calls. All other steps must be zero-token scripts.
+
+---
+
+## Target workflow (per audit cycle)
+
+```
+1.  node dist/index.js audit-code
+      → emits run_id + pending-audit-tasks.json
+
+2.  node dispatch/prepare-dispatch.mjs --run-id <run_id>
+      → reads tasks + schemas → writes dispatch-plan.json
+      (deterministic, 0 LLM tokens)
+
+3.  [Orchestrator reads dispatch-plan.json — small JSON array]
+    [Orchestrator fires N Agent calls in ONE message, verbatim prompts from plan]
+
+      Each subagent (×N, parallel):
+        - reads source files with Read tool
+        - performs lens audit
+        - writes result to task-results/<sanitized_task_id>.json using Write tool
+        - runs: node dispatch/validate-result.mjs <run_id> <task_id>
+          - if non-zero: fixes errors, rewrites, re-validates (max 3 attempts)
+          - if still failing after 3: writes empty-but-valid fallback result
+
+4.  node dispatch/merge-results.mjs --run-id <run_id>
+      → validates all task-results/*.json
+      → writes audit-results.json (passing results only)
+      → writes failed-tasks.json (task_ids that failed validation)
+      (deterministic, 0 LLM tokens)
+
+5.  node dist/index.js worker-run --run-id <run_id>
+      → ingests audit-results.json → coverage matrix → marks tasks complete
+      (deterministic, 0 LLM tokens)
+
+6.  Repeat from step 1 until no pending tasks remain.
+```
+
+Orchestrator token cost per cycle: **~50 tokens × N tasks** (read dispatch-plan + invoke Agent calls). Independent of source file sizes.
+
+---
+
+## Files to create
+
+```
+dispatch/
+  lens-definitions.json       — lens descriptions embedded in every subagent prompt
+  validate.mjs                — shared validation logic (imported by other scripts)
+  validate-result.mjs         — CLI: validate one task-results file
+  prepare-dispatch.mjs        — reads pending tasks → writes dispatch-plan.json
+  merge-results.mjs           — merges validated task results → audit-results.json
+```
+
+## Files to modify
+
+```
+package.json                  — add ajv devDependency; add dispatch:* npm scripts
+```
+
+> **Do NOT add `dispatch/` to the `files` array in package.json.** These scripts are
+> local dev tooling and must not be published to npm.
+
+---
+
+## Step 1 — Add `ajv` dependency
+
+In `package.json`, add to `devDependencies`:
+
+```json
+"ajv": "^8.17.1"
+```
+
+Then run `npm install`.
+
+AJV v8 is required for JSON Schema draft 2020-12 support (which the existing schemas use).
+No other new dependencies are needed.
+
+Also add npm scripts (optional convenience aliases):
+
+```json
+"dispatch:prepare": "node dispatch/prepare-dispatch.mjs",
+"dispatch:merge":   "node dispatch/merge-results.mjs",
+"dispatch:validate": "node dispatch/validate-result.mjs"
+```
+
+---
+
+## Step 2 — Create `dispatch/lens-definitions.json`
+
+This file is embedded verbatim in every subagent prompt. It must be accurate enough that
+a subagent can scope its review correctly without reading any other files.
+
+```json
+{
+  "correctness": {
+    "description": "Logic errors, incorrect algorithm implementations, off-by-one bugs, type mismatches, wrong return values, incorrect state transitions, missing null/undefined guards, misuse of APIs. Focus on code that does the wrong thing.",
+    "do_not_report": "Style issues, naming problems, missing tests, or findings that belong to other lenses."
+  },
+  "maintainability": {
+    "description": "Code that is hard to change safely: excessive function length, deep nesting, tight coupling between unrelated modules, poor naming, magic constants, duplicated logic, inconsistent abstractions, unclear public APIs.",
+    "do_not_report": "Correctness bugs, test gaps, or operational concerns."
+  },
+  "tests": {
+    "description": "Test coverage gaps for important paths, tests that assert incorrect behavior (pinning bugs as expected), fragile or non-deterministic tests, missing negative/edge-case tests, tests that silently pass on stale builds (e.g. importing compiled dist/ rather than source).",
+    "do_not_report": "Source code bugs — report only issues with the tests themselves."
+  },
+  "security": {
+    "description": "Injection vulnerabilities (SQL, shell, path traversal), authentication/authorization flaws, secret exposure, insecure deserialization, privilege escalation, unsafe use of eval or child processes with user input.",
+    "do_not_report": "Performance or correctness issues that are not security-relevant."
+  },
+  "reliability": {
+    "description": "Failure modes without recovery, missing timeouts, unhandled promise rejections, race conditions, resource leaks (file handles, sockets, timers), incorrect retry logic, cascading failure risks.",
+    "do_not_report": "Correctness bugs that do not affect reliability under failure conditions."
+  },
+  "performance": {
+    "description": "Algorithmic inefficiencies (O(n²) where O(n) is possible), unnecessary re-computation, missing caching, synchronous blocking in hot paths, excessive memory allocation.",
+    "do_not_report": "Correctness bugs unrelated to performance."
+  },
+  "data_integrity": {
+    "description": "Missing input validation at trust boundaries, schema violations, inconsistent field naming across related schemas, data loss scenarios, missing required fields, enum values that are present in some schemas but not others.",
+    "do_not_report": "UI or presentation issues; operational or deployment concerns."
+  },
+  "operability": {
+    "description": "Missing or low-quality log output, error messages that don't help operators diagnose problems, missing progress indicators for long operations, no elapsed-time reporting, lack of dry-run or preview modes for destructive operations.",
+    "do_not_report": "Correctness bugs or deployment configuration."
+  },
+  "config_deployment": {
+    "description": "CI/CD pipeline correctness (wrong triggers, missing branch filters, floating version pins), deployment safety (no gate before publish, missing rollback), insecure secret handling in configs, mutable action tags that should be pinned to commit SHAs.",
+    "do_not_report": "Runtime code issues; findings that belong to other lenses."
+  }
+}
+```
+
+---
+
+## Step 3 — Create `dispatch/validate.mjs`
+
+Shared validation module. Exports a single function `validateResult(resultObj, fileLineCounts)`.
+
+### Interface
+
+```js
+/**
+ * @param {object} resultObj  — parsed JSON from a task-results file
+ * @param {Record<string, number>} fileLineCounts — from the task's file_line_counts
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateResult(resultObj, fileLineCounts) { ... }
+```
+
+### Logic
+
+```
+1. AJV validate resultObj against schemas/audit_result.schema.json
+   - Load finding.schema.json first (addSchema) so $ref resolves
+   - Use Ajv({ strict: false }) to avoid complaints about unknown keywords like $schema
+   - On failure: return { valid: false, errors: ajv.errors.map(e => formatAjvError(e)) }
+
+2. Extra check — line range constraint:
+   For each finding in resultObj.findings:
+     For each entry in finding.affected_files:
+       if entry.line_end is defined:
+         look up total_lines from resultObj.file_coverage where path === entry.path
+         if total_lines is undefined: push error "affected_files path '${entry.path}' not in file_coverage"
+         else if entry.line_end > total_lines: push error
+           "finding '${finding.id}': line_end ${entry.line_end} exceeds total_lines ${total_lines} for ${entry.path}"
+
+3. Extra check — lens consistency:
+   For each finding in resultObj.findings:
+     if finding.lens !== resultObj.lens:
+       push error "finding '${finding.id}': lens '${finding.lens}' does not match task lens '${resultObj.lens}'"
+
+4. Extra check — affected_files paths in scope:
+   Collect allowed paths from resultObj.file_coverage[].path
+   For each finding's affected_files entry:
+     if entry.path not in allowed paths:
+       push error "finding '${finding.id}': affected path '${entry.path}' not in task file_coverage"
+
+5. If any extra-check errors: return { valid: false, errors }
+
+6. Return { valid: true, errors: [] }
+```
+
+### Schema loading
+
+Schemas are resolved relative to the project root. Use this logic to find the project root:
+
+```js
+// dispatch/validate.mjs
+import { createRequire } from "node:module";
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+import Ajv from "ajv";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// dispatch/ is one level below project root
+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;
+function getAjv() {
+  if (_ajv) return _ajv;
+  _ajv = new Ajv({ strict: false, allErrors: true });
+  _ajv.addSchema(loadSchema("finding.schema.json"));
+  return _ajv;
+}
+```
+
+---
+
+## Step 4 — Create `dispatch/validate-result.mjs`
+
+CLI wrapper for use by subagents after writing their result file.
+
+### Usage
+
+```
+node dispatch/validate-result.mjs <run_id> <task_id>
+```
+
+- `run_id`: e.g. `20260424T152454170Z_audit_tasks_completed_001`
+- `task_id`: e.g. `src-adapters:correctness` (unsanitized — the script sanitizes internally)
+
+### Logic
+
+```
+1. Parse argv: run_id = process.argv[2], task_id = process.argv[3]
+   If either missing: print usage and exit 1
+
+2. Locate artifacts_dir:
+   Read .audit-artifacts/session-config.json to find artifacts_dir.
+   If not present, default: join(PROJECT_ROOT, ".audit-artifacts")
+
+3. Derive file path:
+   sanitized = task_id.replace(/[^a-zA-Z0-9_-]/g, "_")
+   resultPath = join(artifactsDir, "runs", run_id, "task-results", sanitized + ".json")
+
+4. Read and parse resultPath. If file not found or invalid JSON:
+   print error, exit 1
+
+5. Load the task from pending-audit-tasks.json to get file_line_counts:
+   tasksPath = join(artifactsDir, "runs", run_id, "pending-audit-tasks.json")
+   tasks = JSON.parse(readFileSync(tasksPath))
+   task = tasks.find(t => t.task_id === task_id)
+   fileLineCounts = task?.file_line_counts ?? {}
+
+6. Call validateResult(resultObj, fileLineCounts) from validate.mjs
+
+7. If valid: console.log("✓ valid:", task_id); exit 0
+   If invalid:
+     console.error("✗ invalid:", task_id);
+     console.error(JSON.stringify(errors, null, 2));
+     exit 1
+```
+
+---
+
+## Step 5 — Create `dispatch/prepare-dispatch.mjs`
+
+Core script. Reads pending tasks and produces a ready-to-use dispatch plan.
+
+### Usage
+
+```
+node dispatch/prepare-dispatch.mjs --run-id <run_id>
+```
+
+### Logic
+
+```
+1. Parse --run-id <run_id> from argv. Error if missing.
+
+2. Resolve paths:
+   artifactsDir = join(PROJECT_ROOT, ".audit-artifacts")
+   runDir = join(artifactsDir, "runs", run_id)
+   tasksPath = join(runDir, "pending-audit-tasks.json")
+   dispatchPlanPath = join(runDir, "dispatch-plan.json")
+
+3. Read pending-audit-tasks.json — array of AuditTask objects.
+   If file not found: error and exit 1.
+
+4. Load shared content (read once, reuse for all tasks):
+   lensDefinitions = read dispatch/lens-definitions.json
+   auditResultSchema = read schemas/audit_result.schema.json
+   findingSchema = read schemas/finding.schema.json
+
+5. For each task in tasks:
+   a. sanitizedId = task.task_id.replace(/[^a-zA-Z0-9_-]/g, "_")
+   b. outputPath = join(runDir, "task-results", sanitizedId + ".json")
+   c. lensDef = lensDefinitions[task.lens]
+   d. totalFileLines = Object.values(task.file_line_counts).reduce((a, b) => a + b, 0)
+   e. description = `Audit ${task.unit_id} (${task.file_paths.length} file(s), ~${totalFileLines} lines) — ${task.lens} lens`
+   f. prompt = buildPrompt(task, lensDef, auditResultSchema, findingSchema, outputPath, run_id, artifactsDir)
+   g. Append { task_id, description, output_path: outputPath, prompt } to plan array
+
+6. Ensure task-results/ directory exists:
+   mkdirSync(join(runDir, "task-results"), { recursive: true })
+
+7. Write plan array to dispatchPlanPath as formatted JSON.
+
+8. Print: "Wrote dispatch-plan.json — N tasks ready for dispatch"
+   Print: "Largest task: <task_id> (~N lines)"
+   Print: ""
+   Print: "--- ORCHESTRATOR INSTRUCTIONS ---"
+   Print: "Read dispatch-plan.json. For each entry, fire one Agent call with:"
+   Print: "  description: <entry.description>"
+   Print: "  prompt: <entry.prompt>"
+   Print: "Fire all N calls in a single message for parallel execution."
+   Print: "When all complete, run: node dispatch/merge-results.mjs --run-id <run_id>"
+```
+
+### `buildPrompt(task, lensDef, auditResultSchema, findingSchema, outputPath, runId, artifactsDir)`
+
+Returns a string. Template (use template literals):
+
+```
+You are a code auditor. Perform a bounded audit of the files listed below under the specified lens.
+
+## Task metadata
+${JSON.stringify(task, null, 2)}
+
+## 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").
+
+file_line_counts gives the expected total line count for each file. Use those exact values for file_coverage[].total_lines in your result.
+
+## 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)
+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.
+
+If you cannot produce a valid result after 3 attempts, write this fallback (substituting real values):
+${JSON.stringify({
+  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."]
+}, null, 2)}
+
+Then validate the fallback passes before finishing.
+```
+
+Note: the fallback JSON in the prompt is pre-computed in `buildPrompt` using the task
+data, not generated by the subagent.
+
+---
+
+## Step 6 — Create `dispatch/merge-results.mjs`
+
+### Usage
+
+```
+node dispatch/merge-results.mjs --run-id <run_id>
+```
+
+### Logic
+
+```
+1. Parse --run-id <run_id> from argv.
+
+2. Resolve paths:
+   taskResultsDir = join(artifactsDir, "runs", run_id, "task-results")
+   auditResultsPath = join(artifactsDir, "runs", run_id, "audit-results.json")
+   failedTasksPath = join(artifactsDir, "runs", run_id, "failed-tasks.json")
+   tasksPath = join(artifactsDir, "runs", run_id, "pending-audit-tasks.json")
+
+3. Read pending-audit-tasks.json to build fileLineCounts map:
+   lineCounts = {}
+   for each task: lineCounts[task.task_id] = task.file_line_counts
+
+4. Read all *.json files from task-results/:
+   files = readdirSync(taskResultsDir).filter(f => f.endsWith(".json"))
+
+5. For each file:
+   a. Parse JSON
+   b. Call validateResult(resultObj, lineCounts[resultObj.task_id] ?? {})
+   c. If valid: push to passing[]
+   d. If invalid: push { task_id: resultObj?.task_id ?? filename, errors } to failing[]
+
+6. Write passing array to audit-results.json (as AuditResult[] — array of passing objects)
+
+7. If failing.length > 0:
+   Write failing array to failed-tasks.json
+   Print warning: "${failing.length} task(s) failed validation and were excluded:"
+   For each: print "  ✗ ${f.task_id}: ${f.errors[0]}" (first error only for brevity)
+
+8. Print: "✓ ${passing.length}/${total} tasks valid → ${auditResultsPath}"
+   If failing.length > 0: print "  Re-run those tasks in the next cycle."
+
+9. Exit 0 regardless (partial ingestion is safe — failed tasks remain pending for requeue).
+```
+
+---
+
+## Step 7 — Update `session-config.json` (optional but recommended)
+
+Add `dispatch_provider` field to `.audit-artifacts/session-config.json`:
+
+```json
+{
+  "provider": "local-subprocess",
+  "dispatch_provider": "claude-desktop",
+  "agent_task_batch_size": 10
+}
+```
+
+This is metadata only for now — no code reads `dispatch_provider` yet. It documents intent and provides the hook for future multi-provider support.
+
+---
+
+## Testing procedure
+
+### Unit test: `validate-result.mjs`
+
+1. Write a minimal valid result to a temp file:
+   ```json
+   {
+     "task_id": "test:correctness",
+     "unit_id": "test",
+     "pass_id": "pass:correctness",
+     "lens": "correctness",
+     "file_coverage": [{"path": "src/foo.ts", "total_lines": 100}],
+     "findings": []
+   }
+   ```
+2. Run: `node dispatch/validate-result.mjs <some_run_id> test:correctness` — expect exit 0
+3. Mutate the file: remove `lens` field — expect exit 1 with error mentioning `lens`
+4. Mutate: add `line_end: 200` on an affected_file with total_lines 100 — expect exit 1
+
+### Integration test: `prepare-dispatch.mjs`
+
+1. Run against the current pending tasks:
+   ```
+   node dispatch/prepare-dispatch.mjs --run-id 20260424T152454170Z_audit_tasks_completed_001
+   ```
+2. Inspect `dispatch-plan.json`: each entry should have `task_id`, `description`, `output_path`, `prompt`
+3. Verify `prompt` contains the task JSON, lens definition, both schemas, and the output path
+
+### Integration test: `merge-results.mjs`
+
+1. Write 2 valid and 1 invalid result to `task-results/`
+2. Run: `node dispatch/merge-results.mjs --run-id <id>`
+3. Verify `audit-results.json` contains exactly the 2 valid results
+4. Verify `failed-tasks.json` contains the 1 invalid task
+5. Verify exit code is 0
+
+---
+
+## Orchestrator usage reference
+
+When `prepare-dispatch.mjs` finishes, it prints the instructions inline. For reference:
+
+```
+1. Run: node dispatch/prepare-dispatch.mjs --run-id <run_id>
+2. Read: .audit-artifacts/runs/<run_id>/dispatch-plan.json
+3. In ONE message, fire one Agent call per entry:
+     Agent({ description: entry.description, prompt: entry.prompt })
+   Fire all calls simultaneously — they run in parallel.
+4. Wait for all subagents to complete.
+5. Run: node dispatch/merge-results.mjs --run-id <run_id>
+6. Run: node dist/index.js worker-run --run-id <run_id>
+7. Run: node dist/index.js audit-code   (to get next batch)
+8. Repeat.
+```
+
+**Important:** The orchestrator should NOT read the pending-audit-tasks.json, NOT read
+any source files, NOT compose any prompts. Everything is pre-built. Just read
+`dispatch-plan.json` and fire the calls verbatim.
+
+---
+
+## Notes and caveats
+
+### Large files (2000+ lines)
+
+Tasks with very large files (e.g. `audit-code-wrapper-lib.mjs` at 2215 lines) will still
+hit quota limits for subagents. The `prepare-dispatch.mjs` script should print a warning
+for tasks exceeding a threshold (e.g. 1500 total lines). These tasks may need to be split
+at the task-builder level — that is a separate concern and not addressed here.
+
+### `audit_results_path` vs per-task files
+
+The existing `renderWorkerPrompt.ts` tells subagents to write to a shared
+`audit-results.json`. The new `prepare-dispatch.mjs`-generated prompts tell subagents to
+write to per-task `task-results/<task_id>.json` files. These are two separate dispatch
+paths — the old path (via `renderWorkerPrompt`) is still used for non-`claude-desktop`
+providers and is not modified by this plan.
+
+### Future: provider abstraction
+
+`prepare-dispatch.mjs` output (`dispatch-plan.json`) is provider-agnostic. A future
+`anthropic-direct` provider could read the same `dispatch-plan.json` and call
+`messages.create()` for each entry via SDK, with no changes to `prepare-dispatch.mjs`.
+
+### ajv and published package
+
+`ajv` is added as a devDependency. The `dispatch/` scripts are NOT in the `files` array
+and are not published. End users of the npm package are unaffected.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",
@@ -11,6 +11,7 @@
     "dist/**",
     "audit-code.mjs",
     "audit-code-wrapper-lib.mjs",
+    "dispatch/**",
     "schemas/**",
     "skills/audit-code/**",
     "scripts/postinstall.mjs",
@@ -36,7 +37,10 @@
     "prepublishOnly": "npm run verify:release",
     "start": "node dist/index.js",
     "audit-code": "node audit-code.mjs",
-    "sample-run": "node dist/index.js sample-run"
+    "sample-run": "node dist/index.js sample-run",
+    "dispatch:prepare": "node dispatch/prepare-dispatch.mjs",
+    "dispatch:merge": "node dispatch/merge-results.mjs",
+    "dispatch:validate": "node dispatch/validate-result.mjs"
   },
   "engines": {
     "node": ">=20"
@@ -62,6 +66,7 @@
   ],
   "devDependencies": {
     "@types/node": "^24.3.0",
+    "ajv": "^8.17.1",
     "typescript": "^5.9.2"
   }
 }

package/scripts/postinstall.mjs

@@ -1,19 +1,27 @@
 #!/usr/bin/env node
 import { homedir } from 'os';
 import { join, dirname } from 'path';
-import { mkdirSync, copyFileSync, existsSync } from 'fs';
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 
-const pkgRoot = dirname(fileURLToPath(new URL('.', import.meta.url)));
-const sourceFile = join(pkgRoot, '..', 'skills', 'audit-code', 'audit-code.prompt.md');
+const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const sourceFile = join(pkgRoot, 'skills', 'audit-code', 'audit-code.prompt.md');
 const destDir = join(homedir(), '.claude', 'commands');
 const destFile = join(destDir, 'audit-code.md');
 
+if (!existsSync(sourceFile)) {
+  console.warn(`audit-code: skill source not found at ${sourceFile} — skipping Claude command install`);
+  process.exit(0);
+}
+
 try {
   mkdirSync(destDir, { recursive: true });
-  copyFileSync(sourceFile, destFile);
-  console.log(`audit-code: installed /audit-code Claude command → ${destFile}`);
+  const action = existsSync(destFile) ? 'updated' : 'installed';
+  // Read then write to avoid Windows file-lock issues with copyFileSync
+  writeFileSync(destFile, readFileSync(sourceFile));
+  console.log(`audit-code: ${action} /audit-code Claude command → ${destFile}`);
 } catch (err) {
-  // Non-fatal — CLI still works, just no slash command autocomplete
   console.warn(`audit-code: could not install Claude command (${err.message})`);
+  console.warn(`  To install manually, run:`);
+  console.warn(`    cp "${sourceFile}" "${destFile}"`);
 }

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

@@ -1,67 +1,111 @@
 ---
-description: Autonomous local loop code auditing — steps the audit-code orchestrator and acts as the LLM worker until the audit completes
+description: Autonomous local loop code auditing — steps the audit-code orchestrator and dispatches parallel subagents until the audit completes
 argument-hint: [target-dir]
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent]
 ---
 
 # `/audit-code` Execution Directive
 
-**SYSTEM DIRECTIVE:** When the user enters `/audit-code` in the chat, you are to assume the role of an autonomous code auditor. You are no longer just a conversational assistant; you must use your local terminal and file-editing tools to act as the "LLM Thinking Worker" for the `auditor-lambda` framework.
+**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.
 
-Follow this execution loop rigidly:
+---
+
+## The Loop
+
+Repeat Steps 1–5 until the audit status is `"complete"`.
+
+---
+
+### Step 1 — Advance the State Machine
+
+Run:
+
+```bash
+node audit-code.mjs
+```
+
+_(Outside the `auditor-lambda` repo itself, use `audit-code` or `npx audit-code` instead.)_
+
+Parse the JSON output. Check `audit_state.status`:
+
+| 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 |
+
+---
+
+### Step 2 — Read the Task
 
-## Step 1: Step the Orchestrator
+Read `.audit-artifacts/dispatch/current-task.json`.
 
-To move the state machine forward, execute the backend framework using your terminal tool:
+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
+
+---
+
+### Step 3 — Prepare the Dispatch Plan
+
+Run:
 
 ```bash
-audit-code
+node dispatch/prepare-dispatch.mjs --run-id <run_id>
 ```
 
-_(If the wrapper is only available as a package dependency in the current repository, `npx audit-code` is equivalent. If you are developing inside the `auditor-lambda` repository itself, prefer `node audit-code.mjs` so the run uses the local wrapper and local `dist/` output instead of a potentially stale global install.)_
+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:
+- `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)
+
+---
+
+### Step 4 — Dispatch All Subagents in Parallel
 
-## Step 2: Handle Blockages (The "Thinking" Phase)
+**In a single message**, fire one `Agent` call per entry in `dispatch-plan.json`:
 
-Read the JSON output from the terminal.
-If the top-level status is `"blocked"`, it means the orchestrator needs your LLM "thinking" capabilities to evaluate code logic.
+```
+Agent({ description: entry.description, prompt: entry.prompt })
+```
 
-To determine what task you have been assigned, use your file-reading tool to inspect:
+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.
 
-- `.audit-artifacts/dispatch/current-task.json`
-- `.audit-artifacts/dispatch/current-tasks.json` when present
-- `.audit-artifacts/dispatch/current-prompt.md`
+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.
+
+---
 
-## Step 3: Audit the Code natively
+### Step 5 — Merge and Ingest
 
-1. Read the specific goals and coverage rules laid out in `current-prompt.md`.
-2. Use your file-reading tool to examine the specific source code files mentioned.
-3. Critically analyze the codebase. Use your deepest reasoning capabilities (e.g., chain of thought) to discover defects, logic errors, or systemic architectural issues requested in the prompt.
+Run in sequence:
 
-## Step 4: Write the Findings
+```bash
+node dispatch/merge-results.mjs --run-id <run_id>
+```
 
-Produce your findings array matching exactly the `AuditResult` JSON schema described in the prompt.
-Do not use `echo` or generic terminal shell strings for large JSON structures to avoid breaking JSON escaping.
-Instead, use your raw **File Edit Tool** to reliably save your results to the exact `audit_results_path` named in `.audit-artifacts/dispatch/current-task.json`.
-If `current-tasks.json` exists, emit one `AuditResult` per assigned task in that batch.
+Then execute the `worker_command` from `current-task.json`. It is a JSON array — join the elements into a shell command and run it.
 
-## Step 5: Feed the Loop
+Loop back to **Step 1**.
 
-Return your results to the state machine by running the exact `worker_command` from `.audit-artifacts/dispatch/current-task.json`.
+---
 
-## Step 6: Loop or Terminate
+### Step 6 — Present Results
 
-Continue repeating Steps 1 through 5 as necessary. The state machine will iterate through structuring, planning, and tasking.
+When `audit_state.status` is `"complete"`, stop the loop. Do **not** run the orchestrator again.
 
-**You must stop the loop when the terminal output has `"status": "complete"`.**
+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.
 
-## Step 7: Presentation
+---
 
-Once the audit is officially complete, DO NOT run the orchestrator again.
-Instead, read the final deterministic report at:
+## Edge Cases
 
-- `audit-report.md`
+**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.
 
-Present the completed audit back to the user with the work blocks first, since
-they are the primary remediation handoff units.
+**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.
 
-Wait for the user to ask you to begin resolving one or more work blocks.
+**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.