auditor-lambda 0.10.8 → 0.11.1

package/dist/orchestrator/ingestionExecutors.js

@@ -112,9 +112,36 @@ export function runResultIngestionExecutor(bundle, results) {
         excludeArtifacts: ["audit_tasks.json"],
     });
     const requeuePayload = buildRequeuePayload(updatedCoverageMatrix, selectiveDeepening.bundle.critical_flows, selectiveDeepening.bundle.flow_coverage, selectiveDeepening.bundle.external_analyzer_results);
+    // Fold pending requeue tasks into the dispatch task list so mandatory
+    // coverage gaps produce actual dispatch packets. Enrich with line-count
+    // hints and dedupe against existing tasks by task_id.
+    const deepenedTasks = selectiveDeepening.bundle.audit_tasks ?? [];
+    const lineIndex = lineIndexFromTasks(deepenedTasks);
+    const sizeIndex = sizeIndexFromManifest(selectiveDeepening.bundle.repo_manifest);
+    const existingTaskIds = new Set(deepenedTasks.map((t) => t.task_id));
+    const pendingRequeueTasks = requeuePayload.tasks
+        .filter((t) => t.status === "pending")
+        .filter((t) => !existingTaskIds.has(t.task_id))
+        .map((t) => ({
+        ...t,
+        file_line_counts: Object.fromEntries(t.file_paths
+            .filter((p) => lineIndex[p] != null)
+            .map((p) => [p, lineIndex[p]])),
+    }));
+    const allDispatchTasks = [...deepenedTasks, ...pendingRequeueTasks];
     const finalBundle = {
         ...selectiveDeepening.bundle,
         requeue_tasks: requeuePayload.tasks,
+        audit_plan_metrics: buildAuditPlanMetrics(allDispatchTasks, {
+            graphBundle: selectiveDeepening.bundle.graph_bundle,
+            lineIndex,
+            sizeIndex,
+        }),
+        review_packets: buildReviewPackets(allDispatchTasks, {
+            graphBundle: selectiveDeepening.bundle.graph_bundle,
+            lineIndex,
+            sizeIndex,
+        }),
     };
     return {
         updated: finalBundle,
@@ -125,7 +152,8 @@ export function runResultIngestionExecutor(bundle, results) {
             ...(runtimeValidationReport ? ["runtime_validation_report.json"] : []),
             "audit_results.jsonl",
             "audit_tasks.json",
-            ...selectiveDeepening.artifacts,
+            "audit_plan_metrics.json",
+            "review_packets.json",
             "requeue_tasks.json",
         ],
         progress_summary: `Ingested ${results.length} audit result entries and refreshed dependent artifacts.` +

package/dist/orchestrator/intentCheckpointExecutor.d.ts

@@ -0,0 +1,3 @@
+import type { ArtifactBundle } from "../io/artifacts.js";
+import type { ExecutorRunResult } from "./executorResult.js";
+export declare function runIntentCheckpointExecutor(bundle: ArtifactBundle, root: string, since?: string): Promise<ExecutorRunResult>;

package/dist/orchestrator/intentCheckpointExecutor.js

@@ -0,0 +1,29 @@
+import { resolveAuditScope } from "./scope.js";
+import { isAuditExcludedStatus } from "../extractors/disposition.js";
+export async function runIntentCheckpointExecutor(bundle, root, since) {
+    const scope = resolveAuditScope({ root, since, bundle });
+    let filesInScope = 0;
+    if (scope.mode === "delta") {
+        filesInScope = scope.seed_files.length + scope.expanded_files.length;
+    }
+    else {
+        // Count auditable files in disposition. Fall back to manifest or 0.
+        const auditableCount = bundle.file_disposition?.files.filter((file) => !isAuditExcludedStatus(file.status)).length ?? (bundle.repo_manifest?.files.length ?? 0);
+        filesInScope = auditableCount;
+    }
+    const intent = {
+        schema_version: "intent-checkpoint/v1",
+        confirmed_at: new Date().toISOString(),
+        scope_summary: `Root: ${root}${scope.since ? ` (since ${scope.since})` : ""}, files in scope: ${filesInScope}`,
+        intent_summary: scope.mode === "delta" ? `delta-audit since ${scope.since}` : "full-audit",
+        confirmed_by: "host",
+    };
+    return {
+        updated: {
+            ...bundle,
+            intent_checkpoint: intent,
+        },
+        artifacts_written: ["intent_checkpoint.json"],
+        progress_summary: `Recorded scope/intent checkpoint: ${intent.scope_summary} (${intent.intent_summary}).`,
+    };
+}

package/dist/orchestrator/lensSelection.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Lens selection resolver for operator-selected audit lenses.
+ *
+ * Accepts the `lenses.selected` array from session-config, validates it,
+ * de-duplicates, sorts with the canonical LENSES registry order, and always
+ * unions in the mandatory base set required for cross-perspective coverage.
+ */
+import { type Lens } from "@audit-tools/shared";
+import type { ValidationIssue } from "@audit-tools/shared";
+/**
+ * The mandatory base lenses that are always included regardless of the
+ * operator's selection. These are required for cross-perspective obligations
+ * that every audit must satisfy.
+ */
+export declare const MANDATORY_LENSES: readonly Lens[];
+/**
+ * Validate the `lenses.selected` session-config value and return any errors.
+ * Returns an empty array when the value is undefined (meaning "all lenses").
+ */
+export declare function validateLensSelection(value: unknown, path?: string): ValidationIssue[];
+/**
+ * Resolve the effective lens set from the operator-selected lenses.
+ *
+ * - When `selected` is undefined/null, returns all lenses (current behavior).
+ * - When `selected` is an array of valid lens names, unions in the mandatory
+ *   base lenses, de-duplicates, and sorts to the canonical LENSES order.
+ */
+export declare function resolveEffectiveLenses(selected: string[] | undefined | null): Lens[];
+/** Returns true when the given lens is in the effective set. */
+export declare function isLensEffective(lens: Lens, effectiveLenses: Lens[]): boolean;
+/** Returns true when the given lens is in the mandatory base set. */
+export declare function isMandatoryLens(lens: Lens): boolean;

package/dist/orchestrator/lensSelection.js

@@ -0,0 +1,69 @@
+/**
+ * Lens selection resolver for operator-selected audit lenses.
+ *
+ * Accepts the `lenses.selected` array from session-config, validates it,
+ * de-duplicates, sorts with the canonical LENSES registry order, and always
+ * unions in the mandatory base set required for cross-perspective coverage.
+ */
+import { LENSES, VALID_LENSES } from "@audit-tools/shared";
+import { pushValidationIssue } from "@audit-tools/shared";
+/**
+ * The mandatory base lenses that are always included regardless of the
+ * operator's selection. These are required for cross-perspective obligations
+ * that every audit must satisfy.
+ */
+export const MANDATORY_LENSES = [
+    "security",
+    "correctness",
+    "reliability",
+    "data_integrity",
+];
+const MANDATORY_LENS_SET = new Set(MANDATORY_LENSES);
+/**
+ * Validate the `lenses.selected` session-config value and return any errors.
+ * Returns an empty array when the value is undefined (meaning "all lenses").
+ */
+export function validateLensSelection(value, path = "lenses.selected") {
+    const issues = [];
+    if (value === undefined || value === null) {
+        return issues;
+    }
+    if (!Array.isArray(value)) {
+        pushValidationIssue(issues, path, `${path} must be an array of lens names.`);
+        return issues;
+    }
+    for (const [index, item] of value.entries()) {
+        if (typeof item !== "string" || !VALID_LENSES.has(item)) {
+            pushValidationIssue(issues, `${path}[${index}]`, `${path}[${index}] "${String(item)}" is not a valid lens. Valid lenses: ${[...LENSES].join(", ")}.`);
+        }
+    }
+    return issues;
+}
+/**
+ * Resolve the effective lens set from the operator-selected lenses.
+ *
+ * - When `selected` is undefined/null, returns all lenses (current behavior).
+ * - When `selected` is an array of valid lens names, unions in the mandatory
+ *   base lenses, de-duplicates, and sorts to the canonical LENSES order.
+ */
+export function resolveEffectiveLenses(selected) {
+    if (selected === undefined || selected === null) {
+        // Default: all lenses.
+        return [...LENSES];
+    }
+    // Filter to valid lenses only (invalid ones are caught by validation; tolerate
+    // them here so the runtime path doesn't throw on a misconfigured file).
+    const validSelected = selected.filter((s) => VALID_LENSES.has(s));
+    // Union with mandatory base lenses.
+    const combined = new Set([...validSelected, ...MANDATORY_LENSES]);
+    // Sort to canonical registry order.
+    return LENSES.filter((lens) => combined.has(lens));
+}
+/** Returns true when the given lens is in the effective set. */
+export function isLensEffective(lens, effectiveLenses) {
+    return effectiveLenses.includes(lens);
+}
+/** Returns true when the given lens is in the mandatory base set. */
+export function isMandatoryLens(lens) {
+    return MANDATORY_LENS_SET.has(lens);
+}

package/dist/orchestrator/planningExecutors.js

@@ -44,17 +44,32 @@ export async function runPlanningExecutor(bundle, root, lineIndex = {}, sizeInde
         ...task,
         status: task.status ?? "pending",
     }));
-    const reviewPackets = buildReviewPackets(taggedAuditTasks, {
+    const requeuePayload = buildRequeuePayload(coverage, bundle.critical_flows, flowCoverage, externalAnalyzerResults);
+    // Fold pending requeue tasks into the dispatch task list so mandatory coverage
+    // gaps produce actual dispatch packets. Enrich with line-count hints from the
+    // index and dedupe against existing audit tasks by task_id so each task
+    // appears exactly once in the merged list.
+    const existingTaskIds = new Set(taggedAuditTasks.map((t) => t.task_id));
+    const pendingRequeueTasks = requeuePayload.tasks
+        .filter((t) => t.status === "pending")
+        .filter((t) => !existingTaskIds.has(t.task_id))
+        .map((t) => ({
+        ...t,
+        file_line_counts: Object.fromEntries(t.file_paths
+            .filter((p) => lineIndex[p] != null)
+            .map((p) => [p, lineIndex[p]])),
+    }));
+    const allDispatchTasks = [...taggedAuditTasks, ...pendingRequeueTasks];
+    const reviewPackets = buildReviewPackets(allDispatchTasks, {
         graphBundle: bundle.graph_bundle,
         lineIndex,
         sizeIndex: resolvedSizeIndex,
     });
-    const auditPlanMetrics = buildAuditPlanMetrics(taggedAuditTasks, {
+    const auditPlanMetrics = buildAuditPlanMetrics(allDispatchTasks, {
         graphBundle: bundle.graph_bundle,
         lineIndex,
         sizeIndex: resolvedSizeIndex,
     });
-    const requeuePayload = buildRequeuePayload(coverage, bundle.critical_flows, flowCoverage, externalAnalyzerResults);
     const scopeSummary = resolvedScope.mode === "delta"
         ? ` Delta scope since ${resolvedScope.since}: ${resolvedScope.seed_files.length} changed file(s) + ${resolvedScope.expanded_files.length} graph neighbour(s) queued; a full audit is advised before release.`
         : "";

package/dist/orchestrator/resultIngestion.d.ts

@@ -1,3 +1,17 @@
 import type { AuditResult, AuditTask, CoverageMatrix } from "../types.js";
 export declare function ingestAuditResults(coverageMatrix: CoverageMatrix, results: AuditResult[]): CoverageMatrix;
 export declare function updateAuditTaskStatuses(tasks: AuditTask[] | undefined, results: AuditResult[]): AuditTask[] | undefined;
+/**
+ * Splits raw (unvalidated) audit results into those whose `task_id` is still in
+ * the active task manifest and those orphaned by a later re-plan (e.g. selective-
+ * deepening tasks pruned in a subsequent round). Orphaned results cannot be
+ * ingested — coverage is keyed by the active task set — and must not abort an
+ * otherwise-valid batch at the ingestion validation gate. Returns the retained
+ * results plus the orphaned task ids so the caller can skip-and-warn, or `null`
+ * when there is nothing to filter (not an array, or no active manifest yet),
+ * signaling the caller to pass the results through unchanged.
+ */
+export declare function partitionOrphanedAuditResults(results: unknown, activeTaskIds: Set<string>): {
+    retained: unknown[];
+    orphanedTaskIds: string[];
+} | null;

package/dist/orchestrator/resultIngestion.js

@@ -32,3 +32,31 @@ export function updateAuditTaskStatuses(tasks, results) {
         };
     });
 }
+/**
+ * Splits raw (unvalidated) audit results into those whose `task_id` is still in
+ * the active task manifest and those orphaned by a later re-plan (e.g. selective-
+ * deepening tasks pruned in a subsequent round). Orphaned results cannot be
+ * ingested — coverage is keyed by the active task set — and must not abort an
+ * otherwise-valid batch at the ingestion validation gate. Returns the retained
+ * results plus the orphaned task ids so the caller can skip-and-warn, or `null`
+ * when there is nothing to filter (not an array, or no active manifest yet),
+ * signaling the caller to pass the results through unchanged.
+ */
+export function partitionOrphanedAuditResults(results, activeTaskIds) {
+    if (!Array.isArray(results) || activeTaskIds.size === 0) {
+        return null;
+    }
+    const orphanedTaskIds = [];
+    const retained = results.filter((entry) => {
+        const taskId = entry && typeof entry === "object" && !Array.isArray(entry) &&
+            typeof entry.task_id === "string"
+            ? entry.task_id
+            : undefined;
+        if (taskId !== undefined && !activeTaskIds.has(taskId)) {
+            orphanedTaskIds.push(taskId);
+            return false;
+        }
+        return true;
+    });
+    return { retained, orphanedTaskIds };
+}

package/dist/orchestrator.d.ts

@@ -3,4 +3,4 @@ export interface TaskBuildOptions {
     pass_prefix?: string;
     limit_lenses?: Lens[];
 }
-export declare function buildAuditTasks(unitManifest: UnitManifest, options?: TaskBuildOptions): AuditTask[];
+export declare function buildAuditTasks(unitManifest: UnitManifest, options?: TaskBuildOptions | string): AuditTask[];

package/dist/orchestrator.js

@@ -1,4 +1,5 @@
 import { isLens } from "./types.js";
+import { coerceJsonObjectArg } from "@audit-tools/shared";
 const DEFAULT_LENS_ORDER = [
     "correctness",
     "architecture",
@@ -43,10 +44,8 @@ function assertUnitManifest(value) {
         assertLensArray(unit.required_lenses, `${label}.required_lenses`);
     });
 }
-function normalizedOptions(options) {
-    if (!isRecord(options)) {
-        throw new TypeError("buildAuditTasks options must be an object.");
-    }
+function normalizedOptions(rawOptions) {
+    const options = coerceJsonObjectArg(rawOptions, "buildAuditTasks options");
     if (options.pass_prefix !== undefined && typeof options.pass_prefix !== "string") {
         throw new TypeError("buildAuditTasks options.pass_prefix must be a string.");
     }

package/dist/prompts/renderWorkerPrompt.js

@@ -23,6 +23,8 @@ export function renderWorkerPrompt(task) {
             `${task.artifacts_dir}/audit_tasks.json`;
         const lines = [
             `Audit run: ${task.run_id}`,
+            `Repository root: ${task.repo_root}`,
+            "Set the shell/tool workdir to the repository root before executing worker_command.",
             `Read: ${tasksPath}`,
             "Scope: review only the tasks listed in the Read file. Do not add tasks,",
             "edit source files, remediate findings, run unrelated audits, or write result_path.",
@@ -40,6 +42,11 @@ export function renderWorkerPrompt(task) {
             "  and include verification {verified, needs_followup, concerns, coverage_concerns,",
             "  confidence_concerns, followup_tasks}.",
             "Constraint: line_end must not exceed total_lines for that file.",
+            "Windows PowerShell: do not pipe an inline foreach statement directly into ConvertTo-Json.",
+            "Assign the foreach output to a variable first, then pipe that variable to ConvertTo-Json.",
+            "PowerShell also unwraps single-element arrays: @(@{...}) collapses to one object, so a one-result",
+            "submission serializes as an object (not a 1-element array) and is rejected. Wrap it yourself:",
+            "'[' + (ConvertTo-Json $obj -Depth 12) + ']', or build the array with Write-Output -NoEnumerate.",
             `Write only the JSON array of AuditResult objects to: ${task.audit_results_path}`,
         ];
         if (usesDeferredWorkerCommand(task)) {
@@ -56,6 +63,8 @@ export function renderWorkerPrompt(task) {
     return [
         `Task: ${task.run_id}`,
         `Executor: ${task.preferred_executor}`,
+        `Repository root: ${task.repo_root}`,
+        "Set the shell/tool workdir to the repository root before executing worker_command.",
         "Execute worker_command from task.json exactly.",
         `Command: ${commandArgv}`,
         "Write result to: " + task.result_path,

package/dist/quota/index.d.ts

@@ -1,6 +1,6 @@
-import type { ResolvedLimits as _ResolvedLimits, LimitConfidence as _LimitConfidence, LimitSource as _LimitSource, HostConcurrencyLimit as _HostConcurrencyLimit, QuotaUsageSnapshot as _QuotaUsageSnapshot, BackoffState as _BackoffState } from "@audit-tools/shared";
-export { resolveLimits, lookupKnownModel, classifyProvider, readQuotaState, writeQuotaState, computeMaxSafeConcurrency, recordWaveOutcome, getQuotaStatePath, decayWeight, applyDecayToEntry, computeBackoffCooldownMs, computeBackoffFailureWeight, computeRampUpConcurrency, setQuotaStateDir, detectRateLimitError, computeCooldownUntil, acquireLock, releaseLock, withFileLock, FileLockTimeoutError, runSlidingWindow, LearnedQuotaSource, CompositeQuotaSource, GenericErrorParser, ClaudeCodeErrorParser, getErrorParserForProvider, } from "@audit-tools/shared";
-export type { LimitResolutionResult, ResolveLimitsOptions, ProviderType, ResolvedLimits, LimitSource, LimitConfidence, HostConcurrencyLimit, HostConcurrencyLimitSource, QuotaState, QuotaStateEntry, ConcurrencyBucket, WaveSchedule, BackoffState, ObservedWaveOutcome, RateLimitDetectionResult, SlidingWindowResult, QuotaSource, QuotaUsageSnapshot, ErrorParser, } from "@audit-tools/shared";
+import type { ResolvedLimits as _ResolvedLimits, LimitConfidence as _LimitConfidence, LimitSource as _LimitSource, HostConcurrencyLimit as _HostConcurrencyLimit, QuotaUsageSnapshot as _QuotaUsageSnapshot, BackoffState as _BackoffState, WaveBindingCap as _WaveBindingCap, DispatchCapacityPoolSummary as _DispatchCapacityPoolSummary } from "@audit-tools/shared";
+export { resolveLimits, lookupKnownModel, classifyProvider, readQuotaState, writeQuotaState, computeMaxSafeConcurrency, recordWaveOutcome, getQuotaStatePath, decayWeight, applyDecayToEntry, computeBackoffCooldownMs, computeBackoffFailureWeight, computeRampUpConcurrency, setQuotaStateDir, detectRateLimitError, computeCooldownUntil, acquireLock, releaseLock, withFileLock, FileLockTimeoutError, runSlidingWindow, LearnedQuotaSource, CompositeQuotaSource, GenericErrorParser, ClaudeCodeErrorParser, getErrorParserForProvider, summarizeDispatchCapacityPools, } from "@audit-tools/shared";
+export type { LimitResolutionResult, ResolveLimitsOptions, ProviderType, ResolvedLimits, LimitSource, LimitConfidence, HostConcurrencyLimit, HostConcurrencyLimitSource, QuotaState, QuotaStateEntry, ConcurrencyBucket, WaveSchedule, BackoffState, ObservedWaveOutcome, RateLimitDetectionResult, SlidingWindowResult, QuotaSource, QuotaUsageSnapshot, ErrorParser, WaveBindingCap, DispatchCapacityPoolSummary, } from "@audit-tools/shared";
 export { scheduleWave, buildProviderModelKey, resolveHostModel } from "@audit-tools/shared";
 export type { ScheduleWaveOptions } from "@audit-tools/shared";
 export { computeDispatchCapacity } from "@audit-tools/shared";
@@ -25,6 +25,8 @@ export interface DispatchQuota {
     wave_size: number;
     estimated_wave_tokens: number;
     cooldown_until: string | null;
+    binding_cap?: _WaveBindingCap;
+    capacity_pools?: _DispatchCapacityPoolSummary[];
     quota_source_snapshot?: _QuotaUsageSnapshot | null;
     backoff_state?: _BackoffState | null;
 }

package/dist/quota/index.js

@@ -1,5 +1,5 @@
 // Re-exported from @audit-tools/shared
-export { resolveLimits, lookupKnownModel, classifyProvider, readQuotaState, writeQuotaState, computeMaxSafeConcurrency, recordWaveOutcome, getQuotaStatePath, decayWeight, applyDecayToEntry, computeBackoffCooldownMs, computeBackoffFailureWeight, computeRampUpConcurrency, setQuotaStateDir, detectRateLimitError, computeCooldownUntil, acquireLock, releaseLock, withFileLock, FileLockTimeoutError, runSlidingWindow, LearnedQuotaSource, CompositeQuotaSource, GenericErrorParser, ClaudeCodeErrorParser, getErrorParserForProvider, } from "@audit-tools/shared";
+export { resolveLimits, lookupKnownModel, classifyProvider, readQuotaState, writeQuotaState, computeMaxSafeConcurrency, recordWaveOutcome, getQuotaStatePath, decayWeight, applyDecayToEntry, computeBackoffCooldownMs, computeBackoffFailureWeight, computeRampUpConcurrency, setQuotaStateDir, detectRateLimitError, computeCooldownUntil, acquireLock, releaseLock, withFileLock, FileLockTimeoutError, runSlidingWindow, LearnedQuotaSource, CompositeQuotaSource, GenericErrorParser, ClaudeCodeErrorParser, getErrorParserForProvider, summarizeDispatchCapacityPools, } from "@audit-tools/shared";
 // Wave scheduler now lives in @audit-tools/shared (single source of truth for
 // both orchestrators). Auditor passes its discovered-limits via the structural
 // DiscoveredRateLimitsInput the shared scheduler accepts.

package/dist/reporting/synthesis.d.ts

@@ -73,3 +73,13 @@ export interface RenderAuditReportOptions {
     scope?: AuditScopeManifest;
 }
 export declare function renderAuditReportMarkdown(report: RenderableAuditReport, options?: RenderAuditReportOptions): string;
+/**
+ * Re-derive the summary fields that can be computed from the existing findings
+ * and work_blocks, bump the contract_version to the current constant, and leave
+ * upstream-derived fields that cannot be reconstructed (audited/excluded counts,
+ * runtime validation breakdown) untouched.
+ *
+ * Safe to call on already-promoted `audit-findings.json` files without access to
+ * the pruned `.audit-tools/audit` working-bundle intermediates.
+ */
+export declare function normalizeExistingFindingsReport(report: AuditFindingsReport): AuditFindingsReport;

package/dist/reporting/synthesis.js

@@ -200,6 +200,7 @@ export function renderAuditReportMarkdown(report, options = {}) {
             lines.push(`- Severity: ${finding.severity}`);
             lines.push(`- Confidence: ${finding.confidence}`);
             lines.push(`- Lens: ${finding.lens}`);
+            lines.push(`- Category: ${finding.category}`);
             if (finding.theme_id) {
                 lines.push(`- Theme: ${finding.theme_id}`);
             }
@@ -236,3 +237,25 @@ export function renderAuditReportMarkdown(report, options = {}) {
     lines.push("");
     return lines.join("\n");
 }
+/**
+ * Re-derive the summary fields that can be computed from the existing findings
+ * and work_blocks, bump the contract_version to the current constant, and leave
+ * upstream-derived fields that cannot be reconstructed (audited/excluded counts,
+ * runtime validation breakdown) untouched.
+ *
+ * Safe to call on already-promoted `audit-findings.json` files without access to
+ * the pruned `.audit-tools/audit` working-bundle intermediates.
+ */
+export function normalizeExistingFindingsReport(report) {
+    return {
+        ...report,
+        contract_version: AUDIT_FINDINGS_CONTRACT_VERSION,
+        summary: {
+            ...report.summary,
+            finding_count: report.findings.length,
+            work_block_count: report.work_blocks.length,
+            severity_breakdown: severityBreakdown(report.findings),
+            lens_breakdown: lensBreakdown(report.findings),
+        },
+    };
+}

package/dist/reporting/synthesisNarrativePrompt.js

@@ -4,7 +4,7 @@ function summarizeFinding(finding) {
         .map((file) => file.path)
         .slice(0, 4)
         .join(", ");
-    return `- ${finding.id} [${finding.severity}/${finding.lens}] ${finding.title} — ${finding.summary}${files ? ` (files: ${files})` : ""}`;
+    return `- ${finding.id} [${finding.severity}/${finding.lens}/${finding.category}] ${finding.title} — ${finding.summary}${files ? ` (files: ${files})` : ""}`;
 }
 /**
  * Prompt for the optional synthesis-narrative pass. The host groups the
@@ -27,6 +27,8 @@ export function renderSynthesisNarrativePrompt(report) {
         "",
         "Do not re-audit the code, change severities, or invent new findings. Use only the findings below; reference them by their exact `id`.",
         "",
+        "When categories distinguish observational contract assessment findings from conceptual design critique findings, keep that distinction visible in themes and top risks instead of flattening them into one architecture bucket.",
+        "",
         "## Summary",
         "",
         `- Findings: ${report.summary.finding_count}`,

package/dist/validation/auditResults.js

@@ -305,7 +305,8 @@ function validateVerificationFollowupTask(task, label, taskId, resultIndex, expe
                     result_index: resultIndex,
                     task_id: taskId,
                     field: `${label}.file_paths[${index}]`,
-                    message: `${label}.file_paths[${index}] references '${path}', which is outside the verification task's file_coverage.`,
+                    message: `${label}.file_paths[${index}] references '${path}', which is outside the verification task's file_coverage. ` +
+                        `Followup tasks list files in 'file_paths' (array of strings), not 'file_coverage'; allowed: ${[...allowedPaths].join(", ")}.`,
                 });
             }
         }
@@ -481,7 +482,8 @@ export function validateAuditResults(results, tasks, options = {}) {
                         result_index: i,
                         task_id: taskId,
                         field: `file_coverage[${j}].path`,
-                        message: `file_coverage path '${entry.path}' is not listed in the task file_paths.`,
+                        message: `file_coverage path '${entry.path}' is not listed in the task file_paths. ` +
+                            `Declare only assigned files; allowed for this task: ${task.file_paths.join(", ")}.`,
                     });
                 }
                 else if (seenCoveragePaths.has(entryNorm)) {
@@ -595,7 +597,9 @@ export function validateAuditResults(results, tasks, options = {}) {
                         result_index: i,
                         task_id: taskId,
                         field: `${label}.affected_files[${k}].path`,
-                        message: `affected_files path '${affected.path}' is not in the declared assigned file_coverage.`,
+                        message: `affected_files path '${affected.path}' is not in the declared assigned file_coverage. ` +
+                            `Add it to this result's file_coverage first` +
+                            (task ? `; the task's assigned files are: ${task.file_paths.join(", ")}.` : "."),
                     });
                     continue;
                 }

package/docs/development.md

@@ -23,9 +23,15 @@ once the work ships.
 npm install
 npm run check
 npm test
+npm run test:single -- tests/next-step.test.mjs
 npm run verify:release
 ```
 
+Run `npm install` from the repository root before running build, check, test, or
+package-scoped workflows in a fresh clone or git worktree. Missing
+`node_modules` can surface as misleading `@audit-tools/shared` export or type
+errors because dependents may resolve stale compiled `dist/` output.
+
 The test suite is intentionally contract-heavy. Update tests when changing
 schema shape, prompt contracts, dispatch behavior, installer output, or release
 workflow semantics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.10.8",
+  "version": "0.11.1",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",
@@ -24,6 +24,7 @@
     "build": "tsc -p tsconfig.json",
     "check": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --import tsx/esm --test tests/*.test.mjs",
+    "test:single": "npm run build && node --import tsx/esm --test",
     "release:patch": "node scripts/release-and-publish.mjs patch --bump-only",
     "release:minor": "node scripts/release-and-publish.mjs minor --bump-only",
     "release:major": "node scripts/release-and-publish.mjs major --bump-only",

package/schemas/audit_findings.schema.json

@@ -86,7 +86,20 @@
           "reproduction": { "type": "array", "minItems": 1, "items": { "type": "string" } },
           "systemic": { "type": "boolean" },
           "related_findings": { "type": "array", "minItems": 1, "items": { "type": "string" } },
-          "theme_id": { "type": "string" }
+          "theme_id": { "type": "string" },
+          "contract_goal_id": { "type": "string" },
+          "contract_obligation_ids": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "verification_obligation_ids": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "targeted_commands": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
         },
         "additionalProperties": false
       }

package/schemas/dispatch_quota.schema.json

@@ -56,7 +56,7 @@
     },
     "source": {
       "type": "string",
-      "enum": ["explicit_config", "cli_flags", "known_metadata", "learned", "default"],
+      "enum": ["explicit_config", "cli_flags", "known_metadata", "provider_default", "learned", "default"],
       "description": "Where the resolved limits came from."
     },
     "host_concurrency_limit": {
@@ -75,7 +75,7 @@
         },
         "source": {
           "type": "string",
-          "enum": ["cli_flags", "session_config", "environment"]
+          "enum": ["cli_flags", "host_reported", "session_config", "environment"]
         },
         "description": {
           "type": "string",
@@ -98,6 +98,90 @@
       "format": "date-time",
       "description": "If non-null, the host should wait until this timestamp before launching the next wave."
     },
+    "binding_cap": {
+      "type": "string",
+      "enum": ["rpm", "tpm", "learned", "fallback", "first_contact", "cooldown", "host_concurrency", "none"],
+      "description": "The most constraining cap across capacity pools."
+    },
+    "capacity_pools": {
+      "type": "array",
+      "description": "Per-pool allocation summaries when dispatch capacity was computed across one or more pools.",
+      "items": {
+        "type": "object",
+        "required": [
+          "pool_id",
+          "slots",
+          "model",
+          "confidence",
+          "source",
+          "resolved_limits",
+          "host_concurrency_limit",
+          "cooldown_until",
+          "estimated_wave_tokens",
+          "binding_cap"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "pool_id": { "type": "string", "minLength": 1 },
+          "slots": { "type": "integer", "minimum": 1 },
+          "model": { "type": ["string", "null"] },
+          "confidence": { "type": "string", "enum": ["high", "medium", "low"] },
+          "source": {
+            "type": "string",
+            "enum": ["explicit_config", "cli_flags", "known_metadata", "provider_default", "learned", "default"]
+          },
+          "resolved_limits": {
+            "type": "object",
+            "required": [
+              "context_tokens",
+              "output_tokens",
+              "requests_per_minute",
+              "input_tokens_per_minute",
+              "output_tokens_per_minute"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "context_tokens": { "type": "integer", "minimum": 1 },
+              "output_tokens": { "type": "integer", "minimum": 1 },
+              "requests_per_minute": { "type": ["integer", "null"], "minimum": 1 },
+              "input_tokens_per_minute": { "type": ["integer", "null"], "minimum": 1 },
+              "output_tokens_per_minute": { "type": ["integer", "null"], "minimum": 1 }
+            }
+          },
+          "host_concurrency_limit": {
+            "type": ["object", "null"],
+            "required": ["active_subagents", "source", "description"],
+            "additionalProperties": false,
+            "properties": {
+              "active_subagents": { "type": "integer", "minimum": 1 },
+              "source": {
+                "type": "string",
+                "enum": ["cli_flags", "host_reported", "session_config", "environment"]
+              },
+              "description": { "type": "string", "minLength": 1 }
+            }
+          },
+          "cooldown_until": { "type": ["string", "null"], "format": "date-time" },
+          "estimated_wave_tokens": { "type": "integer", "minimum": 0 },
+          "binding_cap": {
+            "type": "string",
+            "enum": ["rpm", "tpm", "learned", "fallback", "first_contact", "cooldown", "host_concurrency", "none"]
+          },
+          "quota_source_snapshot": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "properties": {
+              "remaining_pct": { "type": ["number", "null"] },
+              "reset_at": { "type": ["string", "null"], "format": "date-time" },
+              "requests_remaining": { "type": ["integer", "null"] },
+              "tokens_remaining": { "type": ["integer", "null"] },
+              "captured_at": { "type": "string", "format": "date-time" },
+              "source": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
     "quota_source_snapshot": {
       "type": ["object", "null"],
       "description": "Real-time usage snapshot from a QuotaSource, if available.",