auditor-lambda 0.11.1 → 0.11.2

package/dist/prompts/renderWorkerPrompt.js

@@ -49,6 +49,7 @@ export function renderWorkerPrompt(task) {
             "'[' + (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/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.1",
+  "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
+}