auditor-lambda 0.12.0 → 0.12.1

package/dist/cli/resynthesizeCommand.js

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { getRootDir } from "./args.js";
 import { normalizeExistingFindingsReport, renderAuditReportMarkdown, } from "../reporting/synthesis.js";
+import { AGENT_FEEDBACK_FILENAME, parseReflectionsNdjson, readOptionalTextFile, } from "@audit-tools/shared";
 const AUDIT_TOOLS_DIR = ".audit-tools";
 const FINDINGS_FILENAME = "audit-findings.json";
 const REPORT_FILENAME = "audit-report.md";
@@ -33,7 +34,13 @@ export async function cmdResynthesize(argv) {
         return;
     }
     const normalized = normalizeExistingFindingsReport(report);
-    const markdown = renderAuditReportMarkdown(normalized);
+    // Best-effort: if the working artifacts dir (and its worker-appended
+    // feedback) still exists — e.g. an interrupted run being compiled by hand —
+    // carry the Process Feedback section into the re-rendered report.
+    const feedbackText = await readOptionalTextFile(join(auditToolsDir, "audit", AGENT_FEEDBACK_FILENAME));
+    const markdown = renderAuditReportMarkdown(normalized, {
+        reflections: feedbackText ? parseReflectionsNdjson(feedbackText) : undefined,
+    });
     await mkdir(auditToolsDir, { recursive: true });
     const outputFindingsPath = join(auditToolsDir, FINDINGS_FILENAME);
     const outputReportPath = join(auditToolsDir, REPORT_FILENAME);

package/dist/io/artifacts.d.ts

@@ -13,6 +13,7 @@ import type { AnalyzerCapabilityRecord } from "../types/analyzerCapability.js";
 import type { AuditScopeManifest } from "../types/auditScope.js";
 import type { ToolingManifest } from "../types/toolingManifest.js";
 import type { ActiveDispatchState } from "../types/activeDispatch.js";
+import { type AgentReflection } from "@audit-tools/shared";
 type ArtifactPayloadMap = {
     repo_manifest: RepoManifest;
     file_disposition: FileDisposition;
@@ -52,9 +53,17 @@ type ArtifactPayloadMap = {
  * the artifacts root rather than as a standard pruned artifact, and carries the
  * in-flight dispatch phase plus any budget-deferred task ids the completion
  * obligation must exclude.
+ *
+ * `agent_reflections` is the parsed view of the worker-APPENDED
+ * `agent-feedback.jsonl` (opt-in meta-audit feedback). Workers own that file;
+ * the orchestrator only ever reads it, so it is deliberately NOT an
+ * ARTIFACT_DEFINITIONS entry — writeCoreArtifacts must never rewrite it (a
+ * round-trip would drop lines a worker appended after load, and prune would
+ * delete a file the orchestrator does not own).
  */
 export type ArtifactBundle = Partial<ArtifactPayloadMap> & {
     active_dispatch?: ActiveDispatchState;
+    agent_reflections?: AgentReflection[];
 };
 export type ArtifactBundleKey = keyof ArtifactPayloadMap;
 type ArtifactPhase = "intake" | "analysis" | "execution" | "reporting" | "supervisor";

package/dist/io/artifacts.js

@@ -1,6 +1,6 @@
 import { cp, rm, unlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { isFileMissingError, readOptionalJsonFile, readOptionalNdjsonFile, readOptionalTextFile, writeJsonFile, writeNdjsonFile, writeTextFile, } from "@audit-tools/shared";
+import { AGENT_FEEDBACK_FILENAME, isFileMissingError, parseReflectionsNdjson, readOptionalJsonFile, readOptionalNdjsonFile, readOptionalTextFile, writeJsonFile, writeNdjsonFile, writeTextFile, } from "@audit-tools/shared";
 import { buildToolingManifest } from "./toolingManifest.js";
 // Canonical filename for the rendered findings report. Single source of truth
 // for path construction. The dependency table below still lists it as plain
@@ -64,6 +64,11 @@ export const ARTIFACT_DEFINITIONS = {
 const ARTIFACT_ENTRIES = Object.entries(ARTIFACT_DEFINITIONS);
 export const ARTIFACT_FILE_TO_BUNDLE_KEY = Object.fromEntries(ARTIFACT_ENTRIES.map(([key, definition]) => [definition.fileName, key]));
 export function getArtifactValue(bundle, artifactName) {
+    // Worker-appended feedback participates in the staleness DAG (its content
+    // hash re-stales audit-report.md) without being a writable registry entry.
+    if (artifactName === AGENT_FEEDBACK_FILENAME) {
+        return bundle.agent_reflections;
+    }
     const key = ARTIFACT_FILE_TO_BUNDLE_KEY[artifactName];
     return key ? bundle[key] : undefined;
 }
@@ -85,6 +90,14 @@ export async function loadArtifactBundle(root) {
     if (activeDispatch !== undefined) {
         bundle.active_dispatch = activeDispatch;
     }
+    // agent-feedback.jsonl is appended by workers (opt-in reflections), never
+    // written by the orchestrator. Parse leniently: malformed lines are skipped,
+    // a present-but-unusable file is just an empty list. Synthesis surfaces the
+    // parsed reflections as the report's "Process Feedback" section.
+    const feedbackText = await readOptionalTextFile(join(root, AGENT_FEEDBACK_FILENAME));
+    if (feedbackText !== undefined) {
+        bundle.agent_reflections = parseReflectionsNdjson(feedbackText);
+    }
     return bundle;
 }
 export async function writeCoreArtifacts(root, bundle, options = {}) {

package/dist/orchestrator/advance.js

@@ -12,7 +12,7 @@ import { runAutoFixExecutor } from "./autoFixExecutor.js";
 import { runSyntaxResolutionExecutor } from "./syntaxResolutionExecutor.js";
 import { runGraphEnrichmentExecutor } from "./graphEnrichmentExecutor.js";
 import { resolveAuditScope } from "./scope.js";
-import { RunLogger } from "@audit-tools/shared";
+import { AGENT_FEEDBACK_FILENAME, RunLogger } from "@audit-tools/shared";
 /**
  * Narrow an optional root to a definite string for an executor that requires
  * it, throwing the canonical "advanceAudit <executor> requires root" error
@@ -234,10 +234,18 @@ export async function advanceAudit(bundle, options = {}) {
             artifact,
         });
     }
-    const metadata = computeArtifactMetadata(run.updated, bundle.artifact_metadata, [...run.artifacts_written, "tooling_manifest.json"]);
+    // tooling_manifest.json and agent-feedback.jsonl are produced outside the
+    // executor loop (environment probe / worker appends), so no executor ever
+    // lists them in artifacts_written. Treat both as always-updated: their
+    // metadata entries are recomputed from live content each advance — unchanged
+    // content keeps its revision (no churn), changed content bumps it so
+    // dependents re-stale exactly once instead of perpetually mismatching a
+    // carried-forward stale hash.
+    const metadata = computeArtifactMetadata(run.updated, bundle.artifact_metadata, [...run.artifacts_written, "tooling_manifest.json", AGENT_FEEDBACK_FILENAME]);
     const metadataBundle = {
         ...run.updated,
         tooling_manifest: bundle.tooling_manifest,
+        agent_reflections: bundle.agent_reflections,
         artifact_metadata: metadata,
     };
     const updatedState = deriveAuditState(metadataBundle);

package/dist/orchestrator/dependencyMap.js

@@ -148,6 +148,16 @@ export const ARTIFACT_DEPENDENTS_MAP = {
     "runtime_validation_report.json": [
         "audit-report.md",
     ],
+    // Opt-in worker reflections (appended by workers, read-only to the
+    // orchestrator; parsed into bundle.agent_reflections). Only the markdown
+    // render depends on it — the "Process Feedback" section — NOT
+    // audit-findings.json, whose machine contract carries no reflections.
+    // advanceAudit hashes it fresh every advance (tooling_manifest pattern), so
+    // a reflection appended after synthesis re-stales the report exactly once
+    // and an unchanged file never churns finalization.
+    "agent-feedback.jsonl": [
+        "audit-report.md",
+    ],
     // The canonical machine contract is co-produced with audit-report.md by the
     // synthesis executor. The optional narrative pass tracks its revision: a fresh
     // (re-synthesized) audit-findings.json re-stales the narrative marker so the

package/dist/orchestrator/synthesisExecutors.js

@@ -34,7 +34,11 @@ export function runSynthesisExecutor(bundle, results) {
         updated: {
             ...bundle,
             audit_findings: findings,
-            audit_report: renderAuditReportMarkdown(findings, { scope: bundle.scope, intent_checkpoint: bundle.intent_checkpoint }),
+            audit_report: renderAuditReportMarkdown(findings, {
+                scope: bundle.scope,
+                intent_checkpoint: bundle.intent_checkpoint,
+                reflections: bundle.agent_reflections,
+            }),
         },
         artifacts_written: ["audit-findings.json", "audit-report.md"],
         progress_summary: `Rendered deterministic audit report and canonical findings for ${finalResults.length} audit result entries.`,
@@ -84,7 +88,11 @@ export function runSynthesisNarrativeExecutor(bundle, narrative) {
         updated: {
             ...bundle,
             audit_findings: enriched,
-            audit_report: renderAuditReportMarkdown(enriched, { scope: bundle.scope, intent_checkpoint: bundle.intent_checkpoint }),
+            audit_report: renderAuditReportMarkdown(enriched, {
+                scope: bundle.scope,
+                intent_checkpoint: bundle.intent_checkpoint,
+                reflections: bundle.agent_reflections,
+            }),
             synthesis_narrative: record,
         },
         artifacts_written: [

package/dist/reporting/synthesis.d.ts

@@ -4,9 +4,9 @@ import type { IntentCheckpoint } from "@audit-tools/shared";
 import type { DesignAssessment } from "../types/designAssessment.js";
 import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
 import type { AuditFindingsReport, CriticalFlowManifest, Finding as SharedFinding, FindingTheme, GraphBundle, SynthesisNarrative } from "@audit-tools/shared";
+import { type AgentReflection } 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";
 /**
@@ -75,8 +75,9 @@ export interface RenderAuditReportOptions {
     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.
+     * section. Omitted/empty renders nothing. Populated from the parsed
+     * `agent-feedback.jsonl` (`bundle.agent_reflections`) by the synthesis
+     * executors.
      */
     reflections?: AgentReflection[];
     /**

package/dist/reporting/synthesis.js

@@ -1,8 +1,7 @@
-import { AUDITOR_REPORT_MARKER } from "@audit-tools/shared";
+import { AUDITOR_REPORT_MARKER, renderProcessFeedbackSection, } 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) {
@@ -82,7 +81,6 @@ export function buildAuditReportModel(params) {
         findings,
         work_blocks: workBlocks,
     };
-    console.error(JSON.stringify({ tag: 'synthesis_complete', finding_count: findings.length, work_block_count: workBlocks.length, severity_breakdown: severityBreakdown(findings), audited_file_count: coverage.audited_file_count, excluded_file_count: coverage.excluded_file_count, budget_deferred_task_count: coverage.budget_deferred_task_count }));
     return model;
 }
 /**
@@ -97,7 +95,6 @@ export function buildAuditFindingsReport(model) {
         findings: model.findings,
         work_blocks: model.work_blocks,
     };
-    console.error(JSON.stringify({ tag: 'audit_findings_report_built', contract_version: AUDIT_FINDINGS_CONTRACT_VERSION, finding_count: model.findings.length, work_block_count: model.work_blocks.length }));
     return report;
 }
 /**

package/package.json

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

package/dist/reporting/agentReflections.d.ts

@@ -1,38 +0,0 @@
-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

@@ -1,162 +0,0 @@
-// 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;
-}