auditor-lambda 0.11.0 → 0.11.2

package/dist/cli/auditStep.js

@@ -6,6 +6,7 @@ import { advanceAudit } from "../orchestrator/advance.js";
 import { deriveAuditState } from "../orchestrator/state.js";
 import { decideNextStep } from "../orchestrator/nextStep.js";
 import { sizeIndexFromManifest } from "../orchestrator/reviewPackets.js";
+import { partitionOrphanedAuditResults } from "../orchestrator/resultIngestion.js";
 import { validateAuditResults, formatAuditResultIssues, } from "../validation/auditResults.js";
 import { formatAuditResultValidationError } from "./workerResult.js";
 import { looksLikeCliFlag, listBatchResultFiles } from "./args.js";
@@ -38,10 +39,23 @@ export async function runAuditStep(options) {
     if (looksLikeCliFlag(options.auditResultsPath)) {
         throw new Error(`Invalid audit results path '${options.auditResultsPath}'. This looks like a CLI flag rather than a file path.`);
     }
-    const auditResults = options.auditResultsPath
+    let auditResults = options.auditResultsPath
         ? await readJsonFile(options.auditResultsPath)
         : undefined;
     if (auditResults !== undefined) {
+        // Drop results whose task_id is no longer in the active manifest — e.g.
+        // selective-deepening tasks pruned by a later re-plan, whose orphaned answers
+        // would otherwise abort the whole batch at the validation gate below and
+        // strand every valid result. They cannot be ingested (coverage is keyed by
+        // the active task set), so skip-and-warn instead of throwing; results for
+        // KNOWN tasks with real errors still abort. The filtered array is what flows
+        // to advanceAudit, so orphans are neither validated nor ingested.
+        const partition = partitionOrphanedAuditResults(auditResults, new Set((bundle.audit_tasks ?? []).map((task) => task.task_id)));
+        if (partition && partition.orphanedTaskIds.length > 0) {
+            process.stderr.write(`audit-results ingestion: skipped ${partition.orphanedTaskIds.length} result(s) whose task_id ` +
+                `is not in the active manifest (orphaned by re-planning): ${partition.orphanedTaskIds.join(", ")}\n`);
+            auditResults = partition.retained;
+        }
         const issues = validateAuditResults(auditResults, bundle.audit_tasks ?? [], {
             lineIndex,
         });

package/dist/cli/dispatch.js

@@ -335,6 +335,9 @@ export function buildPacketPrompt(params) {
         "Produce one JSON array containing exactly one AuditResult object for each listed task.",
         "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.",
         "",
         "Schema file (resolve relative to this prompt's directory): audit_result.schema.json",
         "  $refs resolved from the same directory: finding.schema.json, audit_task.schema.json",

package/dist/extractors/disposition.js

@@ -1,9 +1,16 @@
-import { isNodeModulesOrGit, isTmpPath, isBuildOutput, isVendorPath, isBinaryArtifact, isLicensePath, isLockfilePath, isLogPath, isDocPath, isGeneratedPath, isAuditArtifactPath, isGeneratedTestArtifactPath, isGeneratedInstallArtifactPath, isExamplesOrFixturesPath, normalizeExtractorPath, } from "./pathPatterns.js";
+import { isNodeModulesOrGit, isPackageManagerCachePath, isTmpPath, isBuildOutput, isVendorPath, isBinaryArtifact, isLicensePath, isLockfilePath, isLogPath, isDocPath, isGeneratedPath, isAuditArtifactPath, isAuditToolOutputArtifact, isGeneratedTestArtifactPath, isGeneratedInstallArtifactPath, isExamplesOrFixturesPath, normalizeExtractorPath, } from "./pathPatterns.js";
 function inferDisposition(path) {
     const normalized = normalizeExtractorPath(path);
     if (isNodeModulesOrGit(normalized)) {
         return { path, status: "excluded", reason: "node_modules or .git excluded by convention." };
     }
+    if (isPackageManagerCachePath(normalized)) {
+        return {
+            path,
+            status: "excluded",
+            reason: "Package-manager cache (npm _cacache/npm-cache) excluded by convention.",
+        };
+    }
     if (isTmpPath(normalized)) {
         return {
             path,
@@ -40,6 +47,13 @@ function inferDisposition(path) {
             reason: "Generated audit artifact.",
         };
     }
+    if (isAuditToolOutputArtifact(normalized)) {
+        return {
+            path,
+            status: "generated",
+            reason: "audit-tools pipeline output (findings/report) — a data deliverable, not source.",
+        };
+    }
     if (isGeneratedPath(normalized)) {
         return {
             path,

package/dist/extractors/pathPatterns.d.ts

@@ -24,6 +24,19 @@ export declare function isDocPath(normalized: string): boolean;
 export declare function isGeneratedInstallArtifactPath(normalized: string): boolean;
 export declare function isGeneratedTestArtifactPath(normalized: string): boolean;
 export declare function isAuditArtifactPath(normalized: string): boolean;
+/**
+ * Package-manager cache stores — npm's content-addressed `_cacache`, a nested
+ * `npm-cache`, or a local `.npm` — are dependency blobs, never the audited
+ * project's source. Smoke-test temp dirs can leave these inside the repo tree.
+ */
+export declare function isPackageManagerCachePath(normalized: string): boolean;
+/**
+ * The pipeline's own canonical machine contracts. When audit-tools audits itself
+ * (or any repo that checked one in) these are data deliverables, not source —
+ * auditing them yields only "this is JSON data" noise. The matching `*-report.md`
+ * renders are already handled as `doc_only` by `isDocPath`.
+ */
+export declare function isAuditToolOutputArtifact(normalized: string): boolean;
 export declare function isTestPath(normalized: string): boolean;
 export declare function isInterfacePath(normalized: string): boolean;
 export declare function isDataLayerPath(normalized: string): boolean;

package/dist/extractors/pathPatterns.js

@@ -22,6 +22,9 @@ const BINARY_EXTENSIONS = [
     ".otf",
     ".pdf",
     ".zip",
+    ".tgz",
+    ".tar",
+    ".gz",
 ];
 const LOCKFILE_NAMES = [
     "package-lock.json",
@@ -204,7 +207,31 @@ export function isGeneratedTestArtifactPath(normalized) {
     return splitSegments(normalized).some((segment) => segment.startsWith(".test-") && segment.endsWith("-artifacts"));
 }
 export function isAuditArtifactPath(normalized) {
-    return hasSegment(normalized, ".audit-tools");
+    return (hasSegment(normalized, ".audit-tools") ||
+        hasSegment(normalized, ".audit-artifacts"));
+}
+/**
+ * Package-manager cache stores — npm's content-addressed `_cacache`, a nested
+ * `npm-cache`, or a local `.npm` — are dependency blobs, never the audited
+ * project's source. Smoke-test temp dirs can leave these inside the repo tree.
+ */
+export function isPackageManagerCachePath(normalized) {
+    return (hasSegment(normalized, "_cacache") ||
+        hasSegment(normalized, "npm-cache") ||
+        hasSegment(normalized, ".npm"));
+}
+const AUDIT_TOOL_OUTPUT_BASENAMES = new Set([
+    "audit-findings.json",
+    "remediation-outcomes.json",
+]);
+/**
+ * The pipeline's own canonical machine contracts. When audit-tools audits itself
+ * (or any repo that checked one in) these are data deliverables, not source —
+ * auditing them yields only "this is JSON data" noise. The matching `*-report.md`
+ * renders are already handled as `doc_only` by `isDocPath`.
+ */
+export function isAuditToolOutputArtifact(normalized) {
+    return AUDIT_TOOL_OUTPUT_BASENAMES.has(baseName(normalized));
 }
 export function isTestPath(normalized) {
     const segments = splitSegments(normalized);

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/prompts/renderWorkerPrompt.js

@@ -44,8 +44,12 @@ export function renderWorkerPrompt(task) {
             "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}`,
         ];
+        lines.push("Optional — never let this delay or replace the audit result: if you hit task", "ambiguity, tool friction, or unclear instructions, you MAY append one JSON", `reflection line to ${task.artifacts_dir}/agent-feedback.jsonl with shape:`, "  {task_id, lens, instruction_clarity (clear|mostly_clear|ambiguous|unclear),", "   ambiguities: [string], tool_friction: [string], suggestions: [string],", "   severity (info|low|medium|high)}. One object per line; never overwrite existing lines.");
         if (usesDeferredWorkerCommand(task)) {
             lines.push("Deferred mode: write results, do not execute worker_command.");
         }

package/dist/reporting/agentReflections.d.ts

@@ -0,0 +1,38 @@
+export type ReflectionClarity = "clear" | "mostly_clear" | "ambiguous" | "unclear";
+export type ReflectionSeverity = "info" | "low" | "medium" | "high";
+export interface AgentReflection {
+    task_id: string;
+    lens?: string;
+    instruction_clarity: ReflectionClarity;
+    ambiguities?: string[];
+    tool_friction?: string[];
+    suggestions?: string[];
+    severity: ReflectionSeverity;
+}
+/**
+ * Parse NDJSON reflection text, keeping only schema-valid objects. Blank lines,
+ * non-JSON lines, and objects missing the required `task_id`/`instruction_clarity`/
+ * `severity` (or with out-of-enum values) are skipped silently — the channel is
+ * opt-in and best-effort, so a bad reflection must never break synthesis.
+ */
+export declare function parseReflectionsNdjson(text: string): AgentReflection[];
+export interface ReflectionAggregate {
+    total: number;
+    clarity_breakdown: Record<ReflectionClarity, number>;
+    severity_breakdown: Record<ReflectionSeverity, number>;
+    /** Deduped notes, highest reported impact first (ties broken alphabetically). */
+    friction: string[];
+    ambiguities: string[];
+    suggestions: string[];
+}
+/**
+ * Tally clarity/severity and dedupe the free-text notes across reflections,
+ * ranking each distinct note by the highest severity it was reported under so the
+ * most impactful friction surfaces first.
+ */
+export declare function aggregateReflections(reflections: AgentReflection[]): ReflectionAggregate;
+/**
+ * Render the "## Process Feedback" section. Returns `[]` when there are no
+ * reflections so the report omits the section entirely.
+ */
+export declare function renderProcessFeedbackSection(reflections: AgentReflection[]): string[];

package/dist/reporting/agentReflections.js

@@ -0,0 +1,162 @@
+// Agent meta-audit reflections: a canonical, opt-in feedback channel. Workers may
+// append one reflection per task (NDJSON) to `agent-feedback.jsonl` — schema
+// `schemas/agent_reflection.schema.json`. Synthesis aggregates them into a
+// "Process Feedback" report section so recurring operational friction is visible
+// without hand-reading the JSONL. The channel is best-effort: a malformed line is
+// skipped, never fatal, and never competes with the actual audit obligation.
+const CLARITY_VALUES = new Set([
+    "clear",
+    "mostly_clear",
+    "ambiguous",
+    "unclear",
+]);
+const SEVERITY_VALUES = new Set([
+    "info",
+    "low",
+    "medium",
+    "high",
+]);
+const SEVERITY_RANK = {
+    high: 3,
+    medium: 2,
+    low: 1,
+    info: 0,
+};
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+/**
+ * Parse NDJSON reflection text, keeping only schema-valid objects. Blank lines,
+ * non-JSON lines, and objects missing the required `task_id`/`instruction_clarity`/
+ * `severity` (or with out-of-enum values) are skipped silently — the channel is
+ * opt-in and best-effort, so a bad reflection must never break synthesis.
+ */
+export function parseReflectionsNdjson(text) {
+    const reflections = [];
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        const record = parsed;
+        if (typeof record.task_id !== "string" || record.task_id.length === 0) {
+            continue;
+        }
+        if (typeof record.instruction_clarity !== "string" ||
+            !CLARITY_VALUES.has(record.instruction_clarity)) {
+            continue;
+        }
+        if (typeof record.severity !== "string" ||
+            !SEVERITY_VALUES.has(record.severity)) {
+            continue;
+        }
+        const reflection = {
+            task_id: record.task_id,
+            instruction_clarity: record.instruction_clarity,
+            severity: record.severity,
+        };
+        if (typeof record.lens === "string")
+            reflection.lens = record.lens;
+        if (isStringArray(record.ambiguities))
+            reflection.ambiguities = record.ambiguities;
+        if (isStringArray(record.tool_friction))
+            reflection.tool_friction = record.tool_friction;
+        if (isStringArray(record.suggestions))
+            reflection.suggestions = record.suggestions;
+        reflections.push(reflection);
+    }
+    return reflections;
+}
+/**
+ * Tally clarity/severity and dedupe the free-text notes across reflections,
+ * ranking each distinct note by the highest severity it was reported under so the
+ * most impactful friction surfaces first.
+ */
+export function aggregateReflections(reflections) {
+    const clarity_breakdown = {
+        clear: 0,
+        mostly_clear: 0,
+        ambiguous: 0,
+        unclear: 0,
+    };
+    const severity_breakdown = {
+        info: 0,
+        low: 0,
+        medium: 0,
+        high: 0,
+    };
+    const friction = new Map();
+    const ambiguities = new Map();
+    const suggestions = new Map();
+    const collect = (target, items, severity) => {
+        for (const item of items ?? []) {
+            const key = item.trim();
+            if (key.length === 0)
+                continue;
+            target.set(key, Math.max(target.get(key) ?? 0, SEVERITY_RANK[severity]));
+        }
+    };
+    for (const reflection of reflections) {
+        clarity_breakdown[reflection.instruction_clarity] += 1;
+        severity_breakdown[reflection.severity] += 1;
+        collect(friction, reflection.tool_friction, reflection.severity);
+        collect(ambiguities, reflection.ambiguities, reflection.severity);
+        collect(suggestions, reflection.suggestions, reflection.severity);
+    }
+    const rankedKeys = (target) => [...target.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([key]) => key);
+    return {
+        total: reflections.length,
+        clarity_breakdown,
+        severity_breakdown,
+        friction: rankedKeys(friction),
+        ambiguities: rankedKeys(ambiguities),
+        suggestions: rankedKeys(suggestions),
+    };
+}
+function formatCounts(counts) {
+    const parts = Object.entries(counts)
+        .filter(([, count]) => count > 0)
+        .map(([key, count]) => `${key}: ${count}`);
+    return parts.length > 0 ? parts.join(", ") : "none";
+}
+/**
+ * Render the "## Process Feedback" section. Returns `[]` when there are no
+ * reflections so the report omits the section entirely.
+ */
+export function renderProcessFeedbackSection(reflections) {
+    if (reflections.length === 0)
+        return [];
+    const aggregate = aggregateReflections(reflections);
+    const lines = [
+        "## Process Feedback",
+        "",
+        `Aggregated from ${aggregate.total} agent reflection(s) appended during the run ` +
+            `(opt-in; schema: agent_reflection.schema.json).`,
+        "",
+        `- Instruction clarity: ${formatCounts(aggregate.clarity_breakdown)}`,
+        `- Reported impact: ${formatCounts(aggregate.severity_breakdown)}`,
+        "",
+    ];
+    const block = (title, items) => {
+        if (items.length === 0)
+            return;
+        lines.push(`### ${title}`, "");
+        for (const item of items)
+            lines.push(`- ${item}`);
+        lines.push("");
+    };
+    block("Tool & instruction friction", aggregate.friction);
+    block("Ambiguities", aggregate.ambiguities);
+    block("Suggestions", aggregate.suggestions);
+    return lines;
+}

package/dist/reporting/synthesis.d.ts

@@ -5,6 +5,7 @@ import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
 import type { AuditFindingsReport, CriticalFlowManifest, Finding as SharedFinding, FindingTheme, GraphBundle, SynthesisNarrative } from "@audit-tools/shared";
 import type { RuntimeValidationReport, RuntimeValidationTaskManifest } from "../types/runtimeValidation.js";
 import { type WorkBlock } from "./workBlocks.js";
+import { type AgentReflection } from "./agentReflections.js";
 /** Contract version stamped onto the canonical `audit-findings.json`. */
 export declare const AUDIT_FINDINGS_CONTRACT_VERSION = "audit-tools/audit-findings/v1";
 /**
@@ -71,6 +72,12 @@ export declare function applyNarrative(report: AuditFindingsReport, narrative: S
 export interface RenderAuditReportOptions {
     /** Scope manifest for the run; when delta, the report header reports it honestly. */
     scope?: AuditScopeManifest;
+    /**
+     * Opt-in agent meta-audit reflections to surface in a "Process Feedback"
+     * section. Omitted/empty renders nothing. The synthesis disk-load that
+     * populates this from `agent-feedback.jsonl` is wired separately.
+     */
+    reflections?: AgentReflection[];
 }
 export declare function renderAuditReportMarkdown(report: RenderableAuditReport, options?: RenderAuditReportOptions): string;
 /**

package/dist/reporting/synthesis.js

@@ -2,6 +2,7 @@ import { AUDITOR_REPORT_MARKER } from "@audit-tools/shared";
 import { buildWorkBlocks } from "./workBlocks.js";
 import { mergeFindings } from "./mergeFindings.js";
 import { assignStableFindingIds } from "./findingIdentity.js";
+import { renderProcessFeedbackSection, } from "./agentReflections.js";
 /** Contract version stamped onto the canonical `audit-findings.json`. */
 export const AUDIT_FINDINGS_CONTRACT_VERSION = "audit-tools/audit-findings/v1";
 function countBy(items, selectKey) {
@@ -215,6 +216,7 @@ export function renderAuditReportMarkdown(report, options = {}) {
             lines.push("");
         }
     }
+    lines.push(...renderProcessFeedbackSection(options.reflections ?? []));
     lines.push("## Scope and Coverage", "");
     const scope = options.scope;
     if (scope && scope.mode === "delta") {

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/dist/validation/sessionConfig.js

@@ -1,8 +1,8 @@
-import { exec } from "node:child_process";
+import { execFile } from "node:child_process";
 import { accessSync, constants } from "node:fs";
 import { promisify } from "node:util";
 import { ANALYZER_SETTINGS, PROVIDER_NAMES, SESSION_UI_MODES, isRecord, pushValidationIssue, } from "@audit-tools/shared";
-const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
 const VALID_PROVIDERS = new Set(PROVIDER_NAMES);
 const VALID_UI_MODES = new Set(SESSION_UI_MODES);
 const VALID_ANALYZER_SETTINGS = new Set(ANALYZER_SETTINGS);
@@ -85,7 +85,10 @@ function validateAgentProviderSection(value, path, issues) {
 async function commandExists(command) {
     const lookupCommand = process.platform === "win32" ? "where" : "which";
     try {
-        await execAsync(`${lookupCommand} ${command}`);
+        // execFile (no shell) passes `command` as a literal argv entry, so shell
+        // metacharacters in a config-supplied command cannot be interpreted or
+        // executed during environment validation.
+        await execFileAsync(lookupCommand, [command]);
         return true;
     }
     catch {

package/package.json

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

package/schemas/agent_reflection.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agent_reflection.schema.json",
+  "title": "Agent Reflection",
+  "description": "One opt-in meta-audit reflection appended (NDJSON, one object per line) to agent-feedback.jsonl by a worker, describing how the tool felt to operate. Best-effort and never a substitute for the actual audit/remediation obligation.",
+  "type": "object",
+  "required": ["task_id", "instruction_clarity", "severity"],
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "description": "The audit task or remediation item this reflection is about."
+    },
+    "lens": {
+      "type": "string",
+      "description": "Audit lens (or remediation phase) the worker operated under, when applicable."
+    },
+    "instruction_clarity": {
+      "type": "string",
+      "enum": ["clear", "mostly_clear", "ambiguous", "unclear"],
+      "description": "How clear the task instructions and scope were."
+    },
+    "ambiguities": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Specific things that were unclear about the task, scope, or contracts."
+    },
+    "tool_friction": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Friction encountered operating the tool (commands, prompts, artifacts, environment)."
+    },
+    "suggestions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Concrete suggestions to reduce the friction or ambiguity."
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["info", "low", "medium", "high"],
+      "description": "How much the reported friction/ambiguity impeded the work."
+    }
+  },
+  "additionalProperties": false
+}