auditor-lambda 0.11.2 → 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/reporting/synthesis.d.ts

@@ -1,5 +1,6 @@
 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";
@@ -78,6 +79,11 @@ export interface RenderAuditReportOptions {
      * 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

@@ -217,6 +217,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.0",
   "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
+}