auditor-lambda 0.11.1 → 0.12.0

package/dist/cli/confirmIntentStep.d.ts

@@ -0,0 +1,13 @@
+import type { ScopePreDigest } from "../orchestrator/intentCheckpointExecutor.js";
+/**
+ * Render the host-facing prompt for the `confirm_intent` step. Shows the
+ * deterministically-computed scope picture and asks the host to write (or
+ * refine) `intent_checkpoint.json` — confirming scope/intent and optionally
+ * adding exclusions the disposition pass missed (the scope-pollution case),
+ * must-not-touch globs, and free-form audit intent that is threaded into
+ * worker prompts.
+ */
+export declare function renderConfirmIntentPrompt(preDigest: ScopePreDigest, opts: {
+    intentCheckpointPath: string;
+    continueCommand: string;
+}): string;

package/dist/cli/confirmIntentStep.js

@@ -0,0 +1,68 @@
+/**
+ * Render the host-facing prompt for the `confirm_intent` step. Shows the
+ * deterministically-computed scope picture and asks the host to write (or
+ * refine) `intent_checkpoint.json` — confirming scope/intent and optionally
+ * adding exclusions the disposition pass missed (the scope-pollution case),
+ * must-not-touch globs, and free-form audit intent that is threaded into
+ * worker prompts.
+ */
+export function renderConfirmIntentPrompt(preDigest, opts) {
+    const dirLines = preDigest.scope_dirs
+        .slice(0, 20)
+        .map((d) => `- \`${d.dir}\` — ${d.files} file(s)`)
+        .join("\n") || "_(none)_";
+    const excludedLines = preDigest.auto_excluded.length > 0
+        ? preDigest.auto_excluded
+            .map((e) => `- \`${e.path}\` (${e.status})`)
+            .join("\n")
+        : "_(none)_";
+    return [
+        "# Confirm Audit Scope and Intent",
+        "",
+        "Before planning, confirm what this audit should cover. The scope below was",
+        "discovered deterministically from intake. Your job is to **confirm it** and,",
+        "if needed, **prune scope pollution** the automatic disposition missed (build",
+        "output, vendored code, fixtures, generated files, scratch directories).",
+        "",
+        `**Mode:** ${preDigest.mode}${preDigest.since ? ` (since ${preDigest.since})` : ""}`,
+        `**Files in scope:** ${preDigest.files_in_scope}`,
+        "",
+        "## In-scope top-level directories",
+        "",
+        dirLines,
+        "",
+        "## Already excluded (deterministic disposition)",
+        "",
+        excludedLines,
+        "",
+        "## What to do",
+        "",
+        "Write `intent_checkpoint.json` to:",
+        "",
+        `  ${opts.intentCheckpointPath}`,
+        "",
+        "Use this shape (only `scope_summary` and `intent_summary` are required; add",
+        "the optional fields to constrain the run):",
+        "",
+        "```json",
+        "{",
+        '  "schema_version": "intent-checkpoint/v1",',
+        '  "confirmed_at": "<ISO-8601 timestamp>",',
+        '  "confirmed_by": "host",',
+        '  "scope_summary": "<what is in scope>",',
+        '  "intent_summary": "<the goal, e.g. full-audit / security-focused>",',
+        '  "free_form_intent": "<optional: what to focus on; threaded into worker prompts>",',
+        '  "excluded_scope": [{ "path": "<path or prefix>", "reason": "<why>" }],',
+        '  "must_not_touch": ["<glob>"]',
+        "}",
+        "```",
+        "",
+        "- `excluded_scope` entries are pruned from planning so excluded files never",
+        "  become audit tasks, and they are listed in the final report under",
+        '  "Excluded / Out-of-Scope".',
+        "- Leave the optional fields out to audit the full discovered scope.",
+        "",
+        `Then run: ${opts.continueCommand}`,
+        "",
+    ].join("\n");
+}

package/dist/cli/dispatch.d.ts

@@ -124,6 +124,7 @@ export declare function buildPacketPrompt(params: {
     taskSections: string[];
     submitCommand: string;
     repoRoot?: string;
+    freeFormIntent?: string;
 }): string;
 /**
  * Extracts the context-budget warning loop.

package/dist/cli/dispatch.js

@@ -303,13 +303,17 @@ export function buildTaskSections(packetTasks, lensDefs, lineIndex) {
  * Wraps the 75-line array-join block and returns the assembled prompt string.
  */
 export function buildPacketPrompt(params) {
-    const { packet, fileList, largeFileSection, taskSections, submitCommand, repoRoot } = params;
+    const { packet, fileList, largeFileSection, taskSections, submitCommand, repoRoot, freeFormIntent } = params;
     const largeFileMode = isIsolatedLargeFilePacket(packet);
+    const intentSection = freeFormIntent?.trim()
+        ? ["## Audit intent", freeFormIntent.trim(), ""]
+        : [];
     return [
         "You are a code auditor. Review this packet once, then submit exactly one result per listed task.",
         repoRoot ? `Repository root: ${repoRoot}` : "Repository root: use the root from the step contract.",
         "Set the shell/tool workdir to the repository root when running backend commands.",
         "",
+        ...intentSection,
         "## Packet",
         `packet_id: ${packet.packet_id}`,
         `task_count: ${packet.task_ids.length}`,
@@ -642,7 +646,7 @@ export async function prepareDispatchArtifacts(params) {
                 result_path: resultPathByTaskId.get(task.task_id),
             });
         }
-        const prompt = buildPacketPrompt({ packet, packetTasks, fileList, largeFileSection, taskSections, submitCommand, repoRoot: reviewRoot });
+        const prompt = buildPacketPrompt({ packet, packetTasks, fileList, largeFileSection, taskSections, submitCommand, repoRoot: reviewRoot, freeFormIntent: bundle.intent_checkpoint?.free_form_intent });
         await writeFile(promptPath, prompt, "utf8");
         const packetWritePaths = packetTasks
             .map((task) => resultPathByTaskId.get(task.task_id))

package/dist/cli/nextStepCommand.js

@@ -10,6 +10,7 @@ import { deriveAuditState } from "../orchestrator/state.js";
 import { checkFileIntegrity } from "../orchestrator/fileIntegrity.js";
 import { buildEdgeReasoningPrompt, collectLowConfidenceEdges, edgeReasoningContentHash, } from "../orchestrator/edgeReasoning.js";
 import { renderDesignReviewPrompt } from "../orchestrator/designReviewPrompt.js";
+import { computeScopePreDigest } from "../orchestrator/intentCheckpointExecutor.js";
 import { renderSynthesisNarrativePrompt } from "../reporting/synthesisNarrativePrompt.js";
 import { buildPathLookup } from "../extractors/graph.js";
 import { buildDispositionMap } from "../extractors/disposition.js";
@@ -21,6 +22,7 @@ import { runAuditStep } from "./auditStep.js";
 import { writeHandoffOnly, ensureSemanticReviewRun, persistConfigErrorHandoff, } from "./reviewRun.js";
 import { buildPendingAuditTasks } from "./dispatch.js";
 import { renderSemanticReviewStep } from "./semanticReviewStep.js";
+import { renderConfirmIntentPrompt } from "./confirmIntentStep.js";
 import { writeCurrentStep } from "./steps.js";
 import { nextStepCommand, renderAnalyzerInstallPrompt, renderBlockedStepPrompt, renderEdgeReasoningDispatchPrompt, renderEdgeReasoningStepPrompt, renderPresentReportPrompt, } from "./prompts.js";
 import { getArtifactsDir, getFlag, getHostMaxActiveSubagents, getMaxRuns, getOptionalBooleanFlag, getRootDir, getTimeoutMs, resolveHostDispatchCapability, warnIfNotGitRepo, } from "./args.js";
@@ -344,6 +346,13 @@ async function runDeterministicForNextStep(params) {
                 continue;
             return branch.result;
         }
+        // Confirm-intent host step: when the checkpoint is missing, hand control to
+        // the host to confirm scope/intent. The host writes intent_checkpoint.json
+        // (detected by deriveAuditState on re-invocation), so there is no incoming
+        // artifact to consume — emit the step directly.
+        if (decision.selected_executor === "intent_checkpoint_executor") {
+            return { kind: "confirm_intent", state, bundle };
+        }
         if (isHostDelegationExecutor(decision.selected_executor ?? "")) {
             return {
                 kind: "semantic_review",
@@ -532,6 +541,29 @@ export async function cmdNextStep(argv) {
         console.log(JSON.stringify(step, null, 2));
         return;
     }
+    if (result.kind === "confirm_intent") {
+        const intentCheckpointPath = join(artifactsDir, "intent_checkpoint.json");
+        const continueCommand = nextStepCommand(root, artifactsDir);
+        const preDigest = computeScopePreDigest(result.bundle, root, getFlag(argv, "--since"));
+        const step = await writeCurrentStep({
+            artifactsDir,
+            stepKind: "confirm_intent",
+            status: "ready",
+            runId: null,
+            allowedCommands: [continueCommand],
+            stopCondition: "Write intent_checkpoint.json with the confirmed scope and intent, then run next-step.",
+            repoRoot: root,
+            artifactPaths: {
+                intent_checkpoint: intentCheckpointPath,
+            },
+            prompt: renderConfirmIntentPrompt(preDigest, {
+                intentCheckpointPath,
+                continueCommand,
+            }),
+        });
+        console.log(JSON.stringify(step, null, 2));
+        return;
+    }
     if (result.kind === "analyzer_install") {
         const decisionsPath = join(artifactsDir, "incoming", "analyzer-decisions.json");
         await mkdir(join(artifactsDir, "incoming"), { recursive: true });

package/dist/cli/steps.d.ts

@@ -1,7 +1,7 @@
 import type { StepStatus } from "@audit-tools/shared";
 import type { AccessDeclaration } from "../types/workerSession.js";
 export declare const STEP_CONTRACT_VERSION = "audit-code-step/v1alpha1";
-export type StepKind = "dispatch_review" | "single_task_fallback" | "design_review" | "analyzer_install" | "edge_reasoning" | "edge_reasoning_dispatch" | "synthesis_narrative" | "present_report" | "blocked";
+export type StepKind = "dispatch_review" | "single_task_fallback" | "design_review" | "confirm_intent" | "analyzer_install" | "edge_reasoning" | "edge_reasoning_dispatch" | "synthesis_narrative" | "present_report" | "blocked";
 /**
  * Lightweight run-level orientation surfaced in the step contract so a host
  * resuming an in-flight audit knows where it stands without reading artifacts.

package/dist/orchestrator/advance.js

@@ -3,7 +3,7 @@ import { decideNextStep, findObligation } from "./nextStep.js";
 import { deriveAuditState } from "./state.js";
 import { computeArtifactMetadata } from "./artifactMetadata.js";
 import { runIntakeExecutor } from "./intakeExecutors.js";
-import { runIntentCheckpointExecutor } from "./intentCheckpointExecutor.js";
+import { runIntentCheckpointAutoComplete } from "./intentCheckpointExecutor.js";
 import { runStructureExecutor, runDesignAssessmentExecutor, runDesignReviewAutoComplete, } from "./structureExecutors.js";
 import { runPlanningExecutor } from "./planningExecutors.js";
 import { runResultIngestionExecutor, runRuntimeValidationExecutor, runRuntimeValidationUpdateExecutor, runExternalAnalyzerImportExecutor, } from "./ingestionExecutors.js";
@@ -94,7 +94,7 @@ export async function advanceAudit(bundle, options = {}) {
             }
             case "intent_checkpoint_executor": {
                 const root = requireRoot(options.root, "intent_checkpoint_executor");
-                run = await runIntentCheckpointExecutor(bundle, root, options.since);
+                run = runIntentCheckpointAutoComplete(bundle, root, options.since);
                 break;
             }
             case "structure_executor":

package/dist/orchestrator/executors.js

@@ -16,9 +16,9 @@ export const EXECUTOR_REGISTRY = [
     },
     {
         id: "intent_checkpoint_executor",
-        kind: "deterministic",
+        kind: "host_delegation",
         obligation_ids: ["intent_checkpoint_current"],
-        description: "Write intent_checkpoint.json with confirmed scope and intent.",
+        description: "Pause for the host to confirm scope and intent (the confirm_intent step writes intent_checkpoint.json); deterministic auto-complete writes a default full-scope checkpoint when run headless.",
     },
     {
         id: "structure_executor",

package/dist/orchestrator/intentCheckpointExecutor.d.ts

@@ -1,3 +1,33 @@
 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>;
+/**
+ * Deterministic pre-digest of the audit scope, shown to the host in the
+ * `confirm_intent` step and used to seed the headless auto-complete checkpoint.
+ * Everything here is computed deterministically from the intake artifacts; the
+ * host uses it to confirm the discovered scope and add any exclusions the
+ * disposition pass missed (the scope-pollution case).
+ */
+export interface ScopePreDigest {
+    mode: "full" | "delta";
+    since: string | null;
+    files_in_scope: number;
+    /** Top-level directories of in-scope files, with file counts (desc). */
+    scope_dirs: Array<{
+        dir: string;
+        files: number;
+    }>;
+    /** A sample of files already excluded by the deterministic disposition pass. */
+    auto_excluded: Array<{
+        path: string;
+        status: string;
+    }>;
+}
+export declare function computeScopePreDigest(bundle: ArtifactBundle, root: string, since?: string): ScopePreDigest;
+/**
+ * Headless deterministic fallback for the intent checkpoint — the analog of
+ * `runDesignReviewAutoComplete`. The conversation-first flow instead emits a
+ * `confirm_intent` host step (see `cli/confirmIntentStep.ts`); this runs only
+ * when `advanceAudit` is driven headlessly with no host to confirm scope,
+ * writing a default full-scope checkpoint so the pipeline can proceed.
+ */
+export declare function runIntentCheckpointAutoComplete(bundle: ArtifactBundle, root: string, since?: string): ExecutorRunResult;

package/dist/orchestrator/intentCheckpointExecutor.js

@@ -1,29 +1,60 @@
 import { resolveAuditScope } from "./scope.js";
 import { isAuditExcludedStatus } from "../extractors/disposition.js";
-export async function runIntentCheckpointExecutor(bundle, root, since) {
+const AUTO_EXCLUDED_SAMPLE_LIMIT = 25;
+export function computeScopePreDigest(bundle, root, since) {
     const scope = resolveAuditScope({ root, since, bundle });
-    let filesInScope = 0;
+    const dispositionFiles = bundle.file_disposition?.files ?? [];
+    const auditable = dispositionFiles.filter((file) => !isAuditExcludedStatus(file.status));
+    const excluded = dispositionFiles.filter((file) => isAuditExcludedStatus(file.status));
+    let inScopePaths;
     if (scope.mode === "delta") {
-        filesInScope = scope.seed_files.length + scope.expanded_files.length;
+        inScopePaths = [...scope.seed_files, ...scope.expanded_files];
+    }
+    else if (auditable.length > 0) {
+        inScopePaths = auditable.map((file) => file.path);
     }
     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;
+        inScopePaths = bundle.repo_manifest?.files.map((file) => file.path) ?? [];
+    }
+    const dirCounts = new Map();
+    for (const path of inScopePaths) {
+        const top = path.split(/[\\/]/)[0] || ".";
+        dirCounts.set(top, (dirCounts.get(top) ?? 0) + 1);
     }
+    const scope_dirs = [...dirCounts.entries()]
+        .map(([dir, files]) => ({ dir, files }))
+        .sort((a, b) => b.files - a.files);
+    return {
+        mode: scope.mode === "delta" ? "delta" : "full",
+        since: scope.since ?? null,
+        files_in_scope: inScopePaths.length,
+        scope_dirs,
+        auto_excluded: excluded
+            .slice(0, AUTO_EXCLUDED_SAMPLE_LIMIT)
+            .map((file) => ({ path: file.path, status: file.status })),
+    };
+}
+/**
+ * Headless deterministic fallback for the intent checkpoint — the analog of
+ * `runDesignReviewAutoComplete`. The conversation-first flow instead emits a
+ * `confirm_intent` host step (see `cli/confirmIntentStep.ts`); this runs only
+ * when `advanceAudit` is driven headlessly with no host to confirm scope,
+ * writing a default full-scope checkpoint so the pipeline can proceed.
+ */
+export function runIntentCheckpointAutoComplete(bundle, root, since) {
+    const preDigest = computeScopePreDigest(bundle, root, since);
     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",
+        scope_summary: `Root: ${root}${preDigest.since ? ` (since ${preDigest.since})` : ""}, files in scope: ${preDigest.files_in_scope}`,
+        intent_summary: preDigest.mode === "delta"
+            ? `delta-audit since ${preDigest.since}`
+            : "full-audit",
     };
     return {
-        updated: {
-            ...bundle,
-            intent_checkpoint: intent,
-        },
+        updated: { ...bundle, intent_checkpoint: intent },
         artifacts_written: ["intent_checkpoint.json"],
-        progress_summary: `Recorded scope/intent checkpoint: ${intent.scope_summary} (${intent.intent_summary}).`,
+        progress_summary: `Auto-completed scope/intent checkpoint (headless): ${intent.scope_summary} (${intent.intent_summary}).`,
     };
 }

package/dist/orchestrator/nextStep.js

@@ -9,6 +9,7 @@ export const PRIORITY = [
     "graph_enrichment_current",
     "design_assessment_current",
     "design_review_completed",
+    "intent_checkpoint_current",
     "planning_artifacts",
     "audit_tasks_completed",
     "audit_results_ingested",

package/dist/orchestrator/planningExecutors.js

@@ -1,5 +1,5 @@
 import { initializeCoverageFromPlan } from "./planning.js";
-import { applyScopeToCoverage, fullAuditScope } from "./scope.js";
+import { applyIntentExclusionsToCoverage, applyScopeToCoverage, fullAuditScope, } from "./scope.js";
 import { buildFlowCoverage } from "./flowCoverage.js";
 import { buildRequeuePayload } from "./requeueCommand.js";
 import { buildRuntimeValidationTasks, discoverRuntimeValidationCommand, mergeRuntimeValidationReport, } from "./runtimeValidation.js";
@@ -25,6 +25,9 @@ export async function runPlanningExecutor(bundle, root, lineIndex = {}, sizeInde
     // Delta scope: only seed + expanded files stay pending; the rest inherit prior
     // completion or are excluded from this run. Full scope is a no-op.
     applyScopeToCoverage(coverage, resolvedScope, bundle.coverage_matrix);
+    // Layer the host-confirmed intent exclusions on top of disposition + scope so
+    // user-pruned scope pollution never becomes an audit task.
+    const intentExcludedPaths = applyIntentExclusionsToCoverage(coverage, bundle.intent_checkpoint?.excluded_scope);
     const flowCoverage = buildFlowCoverage(bundle.critical_flows, coverage);
     const runtimeCommand = await discoverRuntimeValidationCommand(root);
     const runtimeValidationTasks = buildRuntimeValidationTasks({
@@ -103,6 +106,9 @@ export async function runPlanningExecutor(bundle, root, lineIndex = {}, sizeInde
             (skippedTrivialPaths.length > 0
                 ? ` Skipped ${skippedTrivialPaths.length} trivial path${skippedTrivialPaths.length === 1 ? "" : "s"} from semantic review.`
                 : "") +
+            (intentExcludedPaths.length > 0
+                ? ` Excluded ${intentExcludedPaths.length} path${intentExcludedPaths.length === 1 ? "" : "s"} per the intent checkpoint.`
+                : "") +
             (runtimeCommand
                 ? ` Runtime validation will use: ${runtimeCommand.join(" ")}.`
                 : " No deterministic runtime validation command was discovered."),

package/dist/orchestrator/scope.d.ts

@@ -60,3 +60,15 @@ export declare function resolveAuditScope(input: ResolveAuditScopeInput): AuditS
  * exclusions (non-auditable/trivial) are left untouched. A full scope is a no-op.
  */
 export declare function applyScopeToCoverage(coverage: CoverageMatrix, scope: AuditScopeManifest, priorCoverage?: CoverageMatrix): CoverageMatrix;
+/**
+ * Apply the intent checkpoint's `excluded_scope` to a coverage matrix: any file
+ * whose path matches an exclusion (exact or directory-prefix) is marked excluded
+ * so it never becomes an audit task. The user's exclusions layer on top of the
+ * deterministic disposition — they catch scope pollution the automatic pass
+ * missed. Returns the newly-excluded paths (for the run summary / report); a
+ * checkpoint with no exclusions is a no-op.
+ */
+export declare function applyIntentExclusionsToCoverage(coverage: CoverageMatrix, excludedScope: Array<{
+    path: string;
+    reason: string;
+}> | undefined): string[];

package/dist/orchestrator/scope.js

@@ -225,3 +225,36 @@ export function applyScopeToCoverage(coverage, scope, priorCoverage) {
     }
     return coverage;
 }
+function pathMatchesExclusion(filePath, entryPath) {
+    const f = filePath.replace(/\\/g, "/");
+    const p = entryPath.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (!p)
+        return false;
+    return f === p || f.startsWith(`${p}/`);
+}
+/**
+ * Apply the intent checkpoint's `excluded_scope` to a coverage matrix: any file
+ * whose path matches an exclusion (exact or directory-prefix) is marked excluded
+ * so it never becomes an audit task. The user's exclusions layer on top of the
+ * deterministic disposition — they catch scope pollution the automatic pass
+ * missed. Returns the newly-excluded paths (for the run summary / report); a
+ * checkpoint with no exclusions is a no-op.
+ */
+export function applyIntentExclusionsToCoverage(coverage, excludedScope) {
+    if (!excludedScope || excludedScope.length === 0)
+        return [];
+    const excluded = [];
+    for (const file of coverage.files) {
+        if (file.audit_status === "excluded")
+            continue;
+        if (excludedScope.some((entry) => pathMatchesExclusion(file.path, entry.path))) {
+            file.required_lenses = [];
+            file.completed_lenses = [];
+            file.unit_ids = [];
+            file.audit_status = "excluded";
+            file.classification_status = "out_of_scope_intent";
+            excluded.push(file.path);
+        }
+    }
+    return excluded;
+}

package/dist/orchestrator/state.js

@@ -32,6 +32,7 @@ export function deriveAuditState(bundle) {
     obligations.push(obligation("graph_enrichment_current", staleOrSatisfied(staleArtifacts, ["analyzer_capability.json"], has(bundle.analyzer_capability))));
     obligations.push(obligation("design_assessment_current", staleOrSatisfied(staleArtifacts, ["design_assessment.json"], has(bundle.design_assessment))));
     obligations.push(obligation("design_review_completed", bundle.design_assessment?.reviewed ? "satisfied" : "missing"));
+    obligations.push(obligation("intent_checkpoint_current", staleOrSatisfied(staleArtifacts, ["intent_checkpoint.json"], has(bundle.intent_checkpoint))));
     const planningReady = has(bundle.coverage_matrix) &&
         has(bundle.flow_coverage) &&
         has(bundle.runtime_validation_tasks) &&

package/dist/orchestrator/synthesisExecutors.js

@@ -1,6 +1,6 @@
 import { applyNarrative, buildAuditFindingsReport, buildAuditReportModel, renderAuditReportMarkdown, } from "../reporting/synthesis.js";
 function buildBaseFindingsReport(bundle, results) {
-    return buildAuditFindingsReport(buildAuditReportModel({
+    const report = buildAuditFindingsReport(buildAuditReportModel({
         results,
         unitManifest: bundle.unit_manifest,
         graphBundle: bundle.graph_bundle,
@@ -11,6 +11,12 @@ function buildBaseFindingsReport(bundle, results) {
         externalAnalyzerResults: bundle.external_analyzer_results,
         designAssessment: bundle.design_assessment,
     }));
+    // Record the host-confirmed exclusions in the machine contract so omissions
+    // are explicit and machine-readable, not just rendered in the markdown.
+    const excludedScope = bundle.intent_checkpoint?.excluded_scope;
+    return excludedScope && excludedScope.length > 0
+        ? { ...report, excluded_scope: excludedScope }
+        : report;
 }
 export function runSynthesisExecutor(bundle, results) {
     const finalResults = results ?? bundle.audit_results ?? [];
@@ -28,7 +34,7 @@ export function runSynthesisExecutor(bundle, results) {
         updated: {
             ...bundle,
             audit_findings: findings,
-            audit_report: renderAuditReportMarkdown(findings, { scope: bundle.scope }),
+            audit_report: renderAuditReportMarkdown(findings, { scope: bundle.scope, intent_checkpoint: bundle.intent_checkpoint }),
         },
         artifacts_written: ["audit-findings.json", "audit-report.md"],
         progress_summary: `Rendered deterministic audit report and canonical findings for ${finalResults.length} audit result entries.`,
@@ -78,7 +84,7 @@ export function runSynthesisNarrativeExecutor(bundle, narrative) {
         updated: {
             ...bundle,
             audit_findings: enriched,
-            audit_report: renderAuditReportMarkdown(enriched, { scope: bundle.scope }),
+            audit_report: renderAuditReportMarkdown(enriched, { scope: bundle.scope, intent_checkpoint: bundle.intent_checkpoint }),
             synthesis_narrative: record,
         },
         artifacts_written: [

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

@@ -1,10 +1,12 @@
 import type { AuditResult, CoverageMatrix, Finding, UnitManifest } from "../types.js";
 import type { AuditScopeManifest } from "../types/auditScope.js";
+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 { 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 +73,17 @@ 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[];
+    /**
+     * The accepted intent checkpoint; its `excluded_scope` is surfaced in an
+     * "Excluded / Out-of-Scope" section so omissions are explicit in the report.
+     */
+    intent_checkpoint?: IntentCheckpoint;
 }
 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,16 @@ export function renderAuditReportMarkdown(report, options = {}) {
             lines.push("");
         }
     }
+    lines.push(...renderProcessFeedbackSection(options.reflections ?? []));
+    const excludedScope = options.intent_checkpoint?.excluded_scope ?? [];
+    if (excludedScope.length > 0) {
+        lines.push("## Excluded / Out-of-Scope", "");
+        lines.push(`${excludedScope.length} path(s) were excluded from this audit per the intent checkpoint:`, "");
+        for (const entry of excludedScope) {
+            lines.push(`- \`${entry.path}\` — ${entry.reason}`);
+        }
+        lines.push("");
+    }
     lines.push("## Scope and Coverage", "");
     const scope = options.scope;
     if (scope && scope.mode === "delta") {

package/dist/validation/artifacts.js

@@ -28,6 +28,15 @@ export function validateArtifactBundle(bundle) {
             "budget",
         ]));
     }
+    if (bundle.intent_checkpoint) {
+        issues.push(...requireKeys(bundle.intent_checkpoint, "intent_checkpoint", [
+            "schema_version",
+            "confirmed_at",
+            "confirmed_by",
+            "scope_summary",
+            "intent_summary",
+        ]));
+    }
     if (bundle.graph_bundle) {
         issues.push(...requireKeys(bundle.graph_bundle, "graph_bundle", ["graphs"]));
     }

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.12.0",
   "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
+}

package/schemas/intent_checkpoint.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "intent_checkpoint.schema.json",
+  "title": "Intent Checkpoint",
+  "description": "intent_checkpoint.json — the accepted scope and intent for a run, confirmed by the host (or auto-completed headlessly) before planning. Single-sourced across audit-code and remediate-code: audit-code consumes `excluded_scope`/`must_not_touch`/`free_form_intent` to prune planning and thread intent into worker prompts; remediate-code additionally uses `filters` to narrow findings. Sits upstream of the planning artifacts in the staleness DAG.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "confirmed_at",
+    "confirmed_by",
+    "scope_summary",
+    "intent_summary"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "intent-checkpoint/v1",
+      "description": "Contract version marker."
+    },
+    "confirmed_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the scope/intent was confirmed."
+    },
+    "confirmed_by": {
+      "const": "host",
+      "description": "Who confirmed the checkpoint (the host, or the headless harness acting as host)."
+    },
+    "scope_summary": {
+      "type": "string",
+      "description": "Human-readable description of the confirmed scope."
+    },
+    "intent_summary": {
+      "type": "string",
+      "description": "Human-readable description of the goal (e.g. full-audit / delta / security-focused)."
+    },
+    "free_form_intent": {
+      "type": "string",
+      "description": "Free-form intent threaded into worker/dispatch prompts."
+    },
+    "excluded_scope": {
+      "type": "array",
+      "description": "Paths intentionally excluded from the run; pruned from planning and listed in the report.",
+      "items": {
+        "type": "object",
+        "required": ["path", "reason"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Path or path prefix to exclude."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Why the path is excluded."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "must_not_touch": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Path globs that must never be written to."
+    },
+    "filters": {
+      "type": "object",
+      "description": "Remediate-only finding filters; audit-code ignores these.",
+      "properties": {
+        "severity": { "type": "array", "items": { "type": "string" } },
+        "lenses": { "type": "array", "items": { "type": "string" } },
+        "packages": { "type": "array", "items": { "type": "string" } },
+        "themes": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}