auditor-lambda 0.11.2 → 0.12.1

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/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/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/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

@@ -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";
@@ -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
@@ -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":
@@ -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/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,11 @@ 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,
+                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.`,
@@ -78,7 +88,11 @@ 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,
+                reflections: bundle.agent_reflections,
+            }),
             synthesis_narrative: record,
         },
         artifacts_written: [

package/dist/reporting/synthesis.d.ts

@@ -1,11 +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 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";
 /**
@@ -74,10 +75,16 @@ 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[];
+    /**
+     * 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

@@ -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;
 }
 /**
@@ -217,6 +214,15 @@ export function renderAuditReportMarkdown(report, options = {}) {
         }
     }
     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/package.json

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

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
+}

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;
-}