auditor-lambda 0.3.3 → 0.3.5

package/docs/dispatch-implementation-plan.md

@@ -1,553 +1,284 @@
-# 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)
-
+# Dispatch Automation Reference
+
+This document describes the implemented review-dispatch path for `/audit-code`.
+The original dispatch plan was one agent per audit task. The current path keeps
+the existing `AuditTask` and `AuditResult` contracts, but groups related tasks
+into review packets so a worker can read a coherent file set once and submit
+one validated result for each assigned task through a backend-owned write path.
+
+## Current Workflow
+
+```text
+1. audit-code
+   -> advances deterministic state until semantic review is needed
+   -> emits a blocked handoff with active_review_run.run_id
+
+2. audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
+   -> reads pending-audit-tasks.json and review planning artifacts
+   -> writes a slim dispatch-plan.json
+   -> writes backend-owned dispatch-result-map.json
+   -> writes one packet prompt per dispatch-plan entry
+   -> prints one compact JSON envelope
+
+3. Conversation orchestrator reads only dispatch-plan.json
+   -> launches one subagent per packet
+   -> each subagent reads its packet prompt and assigned files
+   -> each subagent pipes AuditResult[] to the submit-packet command in the prompt
+   -> submit-packet validates and writes only backend-assigned result files
+   -> each subagent replies: valid: <packet_id>, findings=<n>
+
+4. audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
+   -> validates that every assigned task has exactly one valid result
+   -> rejects missing, unknown, duplicate, malformed, or out-of-scope results
+   -> writes audit-results.json as the existing AuditResult[] shape
+   -> ingests accepted results through the normal result_ingestion_executor
+   -> prints one compact JSON envelope
+
+5. Repeat `audit-code` until complete.
 ```
-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.
 
----
+The parent orchestrator should not read prompt files, pending tasks, completed
+task result payloads, or source files during the packet dispatch path unless a
+backend command fails and the error requires diagnosis.
 
-## Files to create
+## Planning Artifacts
 
-```
-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
-```
+Planning writes two packet-specific artifacts alongside the existing task and
+coverage artifacts:
 
-## Files to modify
+- `review_packets.json`: deterministic packets derived from current
+  `AuditTask` records.
+- `audit_plan_metrics.json`: task count, packet count, repeated file/line
+  estimates, largest packet, and estimated agent-count reduction.
 
-```
-package.json                  — add ajv devDependency; add dispatch:* npm scripts
-```
+Packets preserve task identity. They change the worker-facing unit of work, not
+the backend-owned validation or ingestion contract.
 
-> **Do NOT add `dispatch/` to the `files` array in package.json.** These scripts are
-> local dev tooling and must not be published to npm.
+## Packet Construction
 
----
+Packet planning is deterministic and compatibility-preserving:
 
-## Step 1 — Add `ajv` dependency
+- tasks sharing the same file set and scope are grouped across lenses
+- tiny homogeneous test files are batched before dispatch
+- graph edges from imports, calls, and references can merge related task groups
+- heuristic container edges do not force packet expansion
+- packet chunking respects task-count and line-budget limits
+- a single file that exceeds the packet target is isolated rather than split
+- high-priority packets sort ahead of lower-priority packets
 
-In `package.json`, add to `devDependencies`:
+Generated packets include:
 
 ```json
-"ajv": "^8.17.1"
+{
+  "packet_id": "src-auth:security-correctness:packet-1-...",
+  "task_ids": ["src-auth:security", "src-auth:correctness"],
+  "lenses": ["security", "correctness"],
+  "file_paths": ["src/api/auth.ts", "src/lib/session.ts"],
+  "total_lines": 70,
+  "estimated_tokens": 1180
+}
 ```
 
-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.
+## `prepare-dispatch` Output
 
-Also add npm scripts (optional convenience aliases):
+Command:
 
-```json
-"dispatch:prepare": "node dispatch/prepare-dispatch.mjs",
-"dispatch:merge":   "node dispatch/merge-results.mjs",
-"dispatch:validate": "node dispatch/validate-result.mjs"
+```bash
+audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
 ```
 
----
+Artifacts:
 
-## Step 2 — Create `dispatch/lens-definitions.json`
+- `<artifacts_dir>/runs/<run_id>/dispatch-plan.json`
+- `<artifacts_dir>/runs/<run_id>/dispatch-result-map.json`
+- `<artifacts_dir>/runs/<run_id>/task-results/<packet_id>.prompt.md`
+- `<artifacts_dir>/runs/<run_id>/task-results/<packet_id>.anchors.json`,
+  only for isolated large-file packets
+- `<artifacts_dir>/runs/<run_id>/dispatch-warnings.json`, only when warnings
+  exist
 
-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.
+The command prints a compact JSON envelope:
 
 ```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."
+  "run_id": "run-1",
+  "dispatch_plan_path": ".audit-artifacts/runs/run-1/dispatch-plan.json",
+  "packet_count": 4,
+  "task_count": 18,
+  "largest_packet": {
+    "packet_id": "src-auth:security-correctness:packet-1-...",
+    "total_lines": 1320,
+    "estimated_tokens": 6180
   },
-  "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."
-  }
+  "warning_count": 0,
+  "dispatch_warnings_path": null
 }
 ```
 
----
-
-## Step 3 — Create `dispatch/validate.mjs`
+`dispatch-plan.json` entries are intentionally small:
 
-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;
+```json
+{
+  "packet_id": "src-auth:security-correctness:packet-1-...",
+  "description": "Audit 2 file(s), 2 task(s), 2 lens(es) (~70 lines)",
+  "prompt_path": ".audit-artifacts/runs/run-1/task-results/src-auth_security-correctness_packet-1_ab12cd34ef56.prompt.md"
 }
 ```
 
----
-
-## 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>
+The orchestrator should launch one subagent per entry with the entry
+description and a prompt that tells the subagent to read and follow
+`entry.prompt_path`.
+
+## Large File Mode
+
+The workflow does not impose a hard single-file size limit. When a packet is
+large because it contains one large file, `prepare-dispatch` keeps that file in
+an isolated packet and writes a mechanical anchor summary next to the packet
+prompt. The anchor summary may include:
+
+- file boundaries
+- imports and exports
+- top-level symbols
+- route-like declarations
+- risk keywords
+- graph edges
+- external analyzer signals
+
+The packet prompt points the worker at the anchor file and asks for targeted
+reads/searches within the assigned file. The backend still validates and writes
+results through `submit-packet`. This keeps large-file review bounded by
+mechanically generated structure without slicing files into arbitrary line
+ranges.
+
+## Packet Prompt Contract
+
+Each packet prompt tells the worker to:
+
+- review the packet once
+- read only the listed repo-relative files
+- produce one JSON object per listed task
+- pipe one JSON array to the prompt's `submit-packet` command
+- preserve the existing `AuditResult` fields:
+  `task_id`, `unit_id`, `pass_id`, `lens`, `file_coverage`, `findings`
+- keep `file_coverage[]` as `{ path, total_lines }`
+- keep every finding lens equal to the task lens
+- avoid direct file writes, source edits, remediation, extra task results, and
+  unrelated audits
+- reply exactly `valid: <packet_id>, findings=<total finding count>` after the
+  submit command accepts the packet
+
+This keeps packet review efficient while leaving merge and ingestion
+mechanically deterministic.
+
+## Submission and Validation
+
+Packet submission is exposed through:
+
+```bash
+audit-code submit-packet --run-id <run_id> --packet-id <packet_id> --artifacts-dir <artifacts_dir>
 ```
 
-- `run_id`: e.g. `20260424T152454170Z_audit_tasks_completed_001`
-- `task_id`: e.g. `src-adapters:correctness` (unsanitized — the script sanitizes internally)
+The command reads `AuditResult[]` from stdin, validates the complete assigned
+packet, and writes only the backend-assigned per-task result paths from
+`dispatch-result-map.json`. This keeps result writes out of the LLM prompt and
+prevents swapped or unknown task result files from being ingested.
 
-### Logic
+Per-task validation is exposed through:
 
+```bash
+audit-code validate-result --run-id <run_id> --task-id <task_id> --artifacts-dir <artifacts_dir>
 ```
-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")
+Generated packet prompts may pass run ids, packet ids, task ids, and artifact paths through
+base64url flags such as `--run-id-b64`, `--packet-id-b64`, `--task-id-b64`, and
+`--artifacts-dir-b64` when raw values could contain shell-sensitive characters.
 
-3. Derive file path:
-   sanitized = task_id.replace(/[^a-zA-Z0-9_-]/g, "_")
-   resultPath = join(artifactsDir, "runs", run_id, "task-results", sanitized + ".json")
+The validator checks the result against the assigned task set and enforces the
+mechanical constraints that matter for ingestion:
 
-4. Read and parse resultPath. If file not found or invalid JSON:
-   print error, exit 1
+- required `AuditResult` and finding fields
+- finding lens matches the task lens
+- cited and affected paths are in assigned coverage
+- line spans do not exceed known `total_lines`
+- result fields conform to the shipped schemas
 
-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 ?? {}
+Workers should retry rejected submissions up to the bounded retry count in the prompt.
 
-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
-```
+## `merge-and-ingest` Output
 
----
-
-## 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
+Command:
 
+```bash
+audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
 ```
-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")
+Merge behavior:
 
-3. Read pending-audit-tasks.json to build fileLineCounts map:
-   lineCounts = {}
-   for each task: lineCounts[task.task_id] = task.file_line_counts
+- validates every backend-assigned result-map path
+- rejects unexpected JSON files under `task-results/`
+- rejects task IDs that appear in the wrong assigned result path
+- rejects duplicate task results
+- rejects unknown task IDs
+- rejects missing assigned task results
+- writes `failed-tasks.json` and exits non-zero when any assigned result is
+  missing or invalid
+- writes `audit-results.json` only from passing results
+- invokes the normal result ingestion path only after the assigned set is clean
 
-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`:
+On success the command prints one compact JSON envelope:
 
 ```json
 {
-  "provider": "local-subprocess",
-  "dispatch_provider": "claude-desktop",
-  "agent_task_batch_size": 10
+  "run_id": "run-1",
+  "status": "completed",
+  "accepted_count": 18,
+  "rejected_count": 0,
+  "finding_count": 3,
+  "audit_results_path": ".audit-artifacts/runs/run-1/audit-results.json",
+  "selected_executor": "result_ingestion_executor",
+  "progress_made": true,
+  "progress_summary": "Ingested 18 audit result entries and refreshed dependent artifacts.",
+  "next_likely_step": "runtime_validation"
 }
 ```
 
-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`
+If the command exits non-zero, the orchestrator should stop and report the exact
+error instead of manually editing task results or audit state.
 
-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
+## Selective Deepening
 
-### Integration test: `prepare-dispatch.mjs`
+Result ingestion may add follow-up `AuditTask` records for bounded selective
+deepening. Triggers include:
 
-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
+- high-severity findings
+- low-confidence or ambiguous findings
+- conflicting conclusions across related results
+- high-risk no-finding sampling unless explicitly marked unnecessary
+- runtime-validation disagreement
 
-### Integration test: `merge-results.mjs`
+When follow-up tasks are added, the backend refreshes `review_packets.json` and
+`audit_plan_metrics.json`. The next dispatch cycle handles those tasks through
+the same packet contract.
 
-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
+## Compatibility Notes
 
----
+- `AuditTask` remains the planning and coverage identity.
+- `AuditResult[]` remains the ingestion shape.
+- The older `.audit-artifacts/dispatch/current-*` files still exist for
+  repo-local backend fallback and single-task handoff flows.
+- Backend provider adapters remain compatibility bridges. The canonical
+  `/audit-code` flow expects the active conversation orchestrator to dispatch
+  packet subagents when the host supports them.
+- The `dispatch/` directory is packaged because `lens-definitions.json` and
+  validation support are part of the installed packet workflow.
 
-## Orchestrator usage reference
+## Verification
 
-When `prepare-dispatch.mjs` finishes, it prints the instructions inline. For reference:
+Run the normal project gate:
 
+```bash
+npm test
 ```
-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.
+Focused packet coverage lives in `tests/review-packets.test.mjs` and
+`tests/audit-code-wrapper.test.mjs`.