auditor-lambda 0.10.8 → 0.11.1

package/README.md

@@ -212,11 +212,16 @@ Optional backend config:
 
 ```bash
 npm install
+npm run test:single -- tests/next-step.test.mjs
 npm run verify:release
 npm run release:patch
 npm run release:patch:publish
 ```
 
+When developing from a fresh clone or git worktree, run repo-root `npm install`
+before package checks. Missing workspace links can look like stale
+`@audit-tools/shared` export or type errors.
+
 For GitHub Actions publication and npm Trusted Publishing setup, see `docs/release.md`.
 
 ## Key Docs

package/dist/cli/args.d.ts

@@ -1,4 +1,4 @@
-import type { SessionConfig } from "@audit-tools/shared";
+import { toPromptPathToken, quotePromptCommandArg, type SessionConfig } from "@audit-tools/shared";
 export type UiMode = "visible" | "headless";
 export declare const DIRECT_CLI_DEFAULTS: {
     rootDir: string;
@@ -23,7 +23,7 @@ export declare function fromBase64Url(value: string): string;
 export declare function digestId(value: string): string;
 export declare function safeArtifactStem(value: string): string;
 export declare function artifactNameForId(value: string, extension: string): string;
-export declare function quoteCommandArg(value: string): string;
+export declare const quoteCommandArg: typeof quotePromptCommandArg;
 /**
  * Normalize a generated command token to POSIX path separators. These command
  * strings are embedded in step prompts and `allowed_commands` and run by the
@@ -34,7 +34,7 @@ export declare function quoteCommandArg(value: string): string;
  * are touched, and no non-path argument in this CLI contains one, so this is a
  * targeted normalization rather than a blanket rewrite.
  */
-export declare function toPosixCommandToken(value: string): string;
+export declare const toPosixCommandToken: typeof toPromptPathToken;
 export declare function renderCommand(argv: string[]): string;
 export declare function summarizeLaunchExit(result: {
     accepted?: boolean;

package/dist/cli/args.js

@@ -3,6 +3,7 @@ import { readdir } from "node:fs/promises";
 import { Buffer } from "node:buffer";
 import { createHash } from "node:crypto";
 import { join, resolve } from "node:path";
+import { renderPromptCommand, toPromptPathToken, quotePromptCommandArg, } from "@audit-tools/shared";
 import { resolveFreshSessionProviderName } from "../providers/index.js";
 export const DIRECT_CLI_DEFAULTS = {
     rootDir: ".",
@@ -76,9 +77,7 @@ export function safeArtifactStem(value) {
 export function artifactNameForId(value, extension) {
     return `${safeArtifactStem(value)}_${digestId(value)}.${extension}`;
 }
-export function quoteCommandArg(value) {
-    return /[\s"]/u.test(value) ? `"${value.replace(/"/g, '\\"')}"` : value;
-}
+export const quoteCommandArg = quotePromptCommandArg;
 /**
  * Normalize a generated command token to POSIX path separators. These command
  * strings are embedded in step prompts and `allowed_commands` and run by the
@@ -89,11 +88,9 @@ export function quoteCommandArg(value) {
  * are touched, and no non-path argument in this CLI contains one, so this is a
  * targeted normalization rather than a blanket rewrite.
  */
-export function toPosixCommandToken(value) {
-    return value.includes("\\") ? value.replace(/\\/g, "/") : value;
-}
+export const toPosixCommandToken = toPromptPathToken;
 export function renderCommand(argv) {
-    return argv.map((item) => quoteCommandArg(toPosixCommandToken(item))).join(" ");
+    return renderPromptCommand(argv);
 }
 export function summarizeLaunchExit(result) {
     if (result.accepted !== false && !result.error) {

package/dist/cli/auditStep.js

@@ -6,6 +6,7 @@ import { advanceAudit } from "../orchestrator/advance.js";
 import { deriveAuditState } from "../orchestrator/state.js";
 import { decideNextStep } from "../orchestrator/nextStep.js";
 import { sizeIndexFromManifest } from "../orchestrator/reviewPackets.js";
+import { partitionOrphanedAuditResults } from "../orchestrator/resultIngestion.js";
 import { validateAuditResults, formatAuditResultIssues, } from "../validation/auditResults.js";
 import { formatAuditResultValidationError } from "./workerResult.js";
 import { looksLikeCliFlag, listBatchResultFiles } from "./args.js";
@@ -38,10 +39,23 @@ export async function runAuditStep(options) {
     if (looksLikeCliFlag(options.auditResultsPath)) {
         throw new Error(`Invalid audit results path '${options.auditResultsPath}'. This looks like a CLI flag rather than a file path.`);
     }
-    const auditResults = options.auditResultsPath
+    let auditResults = options.auditResultsPath
         ? await readJsonFile(options.auditResultsPath)
         : undefined;
     if (auditResults !== undefined) {
+        // Drop results whose task_id is no longer in the active manifest — e.g.
+        // selective-deepening tasks pruned by a later re-plan, whose orphaned answers
+        // would otherwise abort the whole batch at the validation gate below and
+        // strand every valid result. They cannot be ingested (coverage is keyed by
+        // the active task set), so skip-and-warn instead of throwing; results for
+        // KNOWN tasks with real errors still abort. The filtered array is what flows
+        // to advanceAudit, so orphans are neither validated nor ingested.
+        const partition = partitionOrphanedAuditResults(auditResults, new Set((bundle.audit_tasks ?? []).map((task) => task.task_id)));
+        if (partition && partition.orphanedTaskIds.length > 0) {
+            process.stderr.write(`audit-results ingestion: skipped ${partition.orphanedTaskIds.length} result(s) whose task_id ` +
+                `is not in the active manifest (orphaned by re-planning): ${partition.orphanedTaskIds.join(", ")}\n`);
+            auditResults = partition.retained;
+        }
         const issues = validateAuditResults(auditResults, bundle.audit_tasks ?? [], {
             lineIndex,
         });

package/dist/cli/dispatch.d.ts

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

package/dist/cli/dispatch.js

@@ -10,7 +10,7 @@ import { orderTasksForPacketReview, buildReviewPackets, sizeIndexFromManifest, }
 import { buildFileAnchorSummary } from "../orchestrator/fileAnchors.js";
 import { resolveFreshSessionProviderName } from "../providers/index.js";
 import { loadSessionConfig } from "../supervisor/sessionConfig.js";
-import { computeDispatchCapacity, buildProviderModelKey, resolveHostModel, readQuotaState, resolveHostActiveSubagentLimit, lookupDiscoveredLimits, mergeDiscoveredLimits, } from "../quota/index.js";
+import { computeDispatchCapacity, buildProviderModelKey, resolveHostModel, readQuotaState, resolveHostActiveSubagentLimit, lookupDiscoveredLimits, mergeDiscoveredLimits, summarizeDispatchCapacityPools, } from "../quota/index.js";
 import { taskResultPath, packetPromptPath, artifactNameForId, toBase64Url, fromBase64Url, getFlag, } from "./args.js";
 export const LARGE_FILE_PACKET_TARGET_LINES = 2500;
 export const SMALL_MODEL_HINT_MAX_LINES = 500;
@@ -303,10 +303,12 @@ 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 } = params;
+    const { packet, fileList, largeFileSection, taskSections, submitCommand, repoRoot } = params;
     const largeFileMode = isIsolatedLargeFilePacket(packet);
     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.",
         "",
         "## Packet",
         `packet_id: ${packet.packet_id}`,
@@ -316,8 +318,8 @@ export function buildPacketPrompt(params) {
         "",
         "## Files to read",
         largeFileMode
-            ? "Use targeted Read/Grep calls. Paths are repo-relative from the current working directory."
-            : "Use your Read tool. Paths are repo-relative from the current working directory.",
+            ? "Use targeted Read/Grep calls. Paths are repo-relative to the repository root above."
+            : "Use your Read tool. Paths are repo-relative to the repository root above.",
         "Use host Read and Grep tools for source inspection. Do not use shell search commands.",
         fileList,
         "",
@@ -331,6 +333,11 @@ export function buildPacketPrompt(params) {
         "packet-*-result.json / audit_result_*.json) — the submit-packet command below is the only",
         "way to record results, and it writes them inside the artifacts directory for you.",
         "Produce one JSON array containing exactly one AuditResult object for each listed task.",
+        "Windows PowerShell: do not pipe an inline foreach statement directly into ConvertTo-Json.",
+        "Assign the foreach output to a variable first, then pipe that variable to ConvertTo-Json.",
+        "PowerShell also unwraps single-element arrays: @(@{...}) collapses to one object, so a",
+        "one-result submission serializes as an object (not a 1-element array) and is rejected. Wrap it",
+        "yourself: '[' + (ConvertTo-Json $obj -Depth 12) + ']', or build the array with Write-Output -NoEnumerate.",
         "",
         "Schema file (resolve relative to this prompt's directory): audit_result.schema.json",
         "  $refs resolved from the same directory: finding.schema.json, audit_task.schema.json",
@@ -437,6 +444,8 @@ async function computeDispatchQuota(params) {
         wave_size: dispatchCapacity.total_slots,
         estimated_wave_tokens: dispatchCapacity.estimated_wave_tokens,
         cooldown_until: dispatchCapacity.cooldown_until,
+        binding_cap: dispatchCapacity.binding_cap,
+        capacity_pools: summarizeDispatchCapacityPools(dispatchCapacity),
         quota_source_snapshot: waveSchedule.quota_source_snapshot ?? null,
         backoff_state: null,
     };
@@ -633,8 +642,11 @@ export async function prepareDispatchArtifacts(params) {
                 result_path: resultPathByTaskId.get(task.task_id),
             });
         }
-        const prompt = buildPacketPrompt({ packet, packetTasks, fileList, largeFileSection, taskSections, submitCommand });
+        const prompt = buildPacketPrompt({ packet, packetTasks, fileList, largeFileSection, taskSections, submitCommand, repoRoot: reviewRoot });
         await writeFile(promptPath, prompt, "utf8");
+        const packetWritePaths = packetTasks
+            .map((task) => resultPathByTaskId.get(task.task_id))
+            .filter((p) => p !== undefined);
         plan.push({
             packet_id: packet.packet_id,
             description: `Audit ${packet.file_paths.length} file(s), ${packet.task_ids.length} task(s), ${packet.lenses.length} lens(es) (~${packet.total_lines} lines)` +
@@ -642,6 +654,16 @@ export async function prepareDispatchArtifacts(params) {
             prompt_path: promptPath,
             complexity,
             model_hint: buildDispatchModelHint(complexity),
+            access: {
+                read_paths: [
+                    promptPath,
+                    ...(reviewRoot
+                        ? packet.file_paths.map((p) => join(reviewRoot, p))
+                        : packet.file_paths),
+                ],
+                write_paths: packetWritePaths,
+                forbidden_patterns: ["packet-*-result.json", "audit_result_*.json"],
+            },
         });
     }
     await writeJsonFile(dispatchPlanPath, plan);

package/dist/cli/prompts.js

@@ -1,4 +1,4 @@
-import { DO_NOT_TOKEN_WRAP_NOTE } from "@audit-tools/shared";
+import { DO_NOT_TOKEN_WRAP_NOTE, DISPATCH_PROMPT_HANDOFF_NOTE } from "@audit-tools/shared";
 import { renderCommand } from "./args.js";
 /**
  * Token prefix the host should use to re-invoke the backend in generated
@@ -93,7 +93,7 @@ export function renderDispatchReviewPrompt(params) {
         ...dispatchDataLines,
         ...canaryLines,
         "",
-        "Pass each `entry.prompt_path` literally to its subagent; do not load packet prompt files into this orchestrator context.",
+        DISPATCH_PROMPT_HANDOFF_NOTE,
         "",
         "Subagent prompt shape:",
         "",
@@ -104,7 +104,7 @@ export function renderDispatchReviewPrompt(params) {
         "",
         "Each subagent must submit its packet through the submit command printed in its packet prompt and stop after successful submission.",
         "",
-        "**File access pre-approval:** Each dispatch plan entry includes an `access` object with `read_paths` and `write_paths`. If your host supports per-subagent file access restrictions, pre-approve those paths before launching each subagent. Workers should not access files outside their declared paths.",
+        "**File access pre-approval:** Each dispatch plan entry includes an `access` object with `read_paths`, `write_paths`, and `forbidden_patterns`. If your host supports per-subagent file access restrictions, pre-approve exactly `entry.access.read_paths` and `entry.access.write_paths` for each subagent. Do not grant broad workspace or task-results directory write access. Workers should not access files outside their declared paths.",
         "",
         "**After all waves complete:**",
         "",
@@ -172,10 +172,11 @@ export function renderEdgeReasoningDispatchPrompt(params) {
         "optional pass: it only rewrites the `reason` string of those edges — it never",
         "adds, removes, re-targets, or re-weights an edge.",
         "",
-        "Dispatch exactly ONE subagent (via the `task` tool or equivalent). Hand it this",
-        "prompt file path; do not load the file into this orchestrator context:",
+        "Dispatch exactly ONE subagent (via the `task` tool or equivalent).",
         "",
-        `  ${params.promptPath}`,
+        DISPATCH_PROMPT_HANDOFF_NOTE,
+        "",
+        `  Prompt path: ${params.promptPath}`,
         "",
         "Subagent prompt shape:",
         "",

package/dist/cli/resynthesizeCommand.d.ts

@@ -0,0 +1 @@
+export declare function cmdResynthesize(argv: string[]): Promise<void>;

package/dist/cli/resynthesizeCommand.js

@@ -0,0 +1,50 @@
+import { join } from "node:path";
+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";
+const AUDIT_TOOLS_DIR = ".audit-tools";
+const FINDINGS_FILENAME = "audit-findings.json";
+const REPORT_FILENAME = "audit-report.md";
+function getFlagValue(argv, flag) {
+    const idx = argv.indexOf(flag);
+    return idx >= 0 && idx + 1 < argv.length ? argv[idx + 1] : undefined;
+}
+export async function cmdResynthesize(argv) {
+    const root = getRootDir(argv);
+    const auditToolsDir = join(root, AUDIT_TOOLS_DIR);
+    const defaultInput = join(auditToolsDir, FINDINGS_FILENAME);
+    const inputPath = getFlagValue(argv, "--input") ?? defaultInput;
+    if (!existsSync(inputPath)) {
+        console.error(`resynthesize: ${FINDINGS_FILENAME} not found at ${inputPath}. ` +
+            `Run the full audit first, or supply --input <path>.`);
+        process.exitCode = 1;
+        return;
+    }
+    const raw = await readFile(inputPath, "utf8");
+    let report;
+    try {
+        report = JSON.parse(raw);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(`resynthesize: could not parse ${inputPath}: ${msg}`);
+        process.exitCode = 1;
+        return;
+    }
+    const normalized = normalizeExistingFindingsReport(report);
+    const markdown = renderAuditReportMarkdown(normalized);
+    await mkdir(auditToolsDir, { recursive: true });
+    const outputFindingsPath = join(auditToolsDir, FINDINGS_FILENAME);
+    const outputReportPath = join(auditToolsDir, REPORT_FILENAME);
+    await writeFile(outputFindingsPath, JSON.stringify(normalized, null, 2), "utf8");
+    await writeFile(outputReportPath, markdown, "utf8");
+    console.log(JSON.stringify({
+        source: inputPath,
+        findings_output: outputFindingsPath,
+        report_output: outputReportPath,
+        finding_count: normalized.summary.finding_count,
+        work_block_count: normalized.summary.work_block_count,
+        contract_version: normalized.contract_version,
+    }, null, 2));
+}

package/dist/cli.js

@@ -23,6 +23,7 @@ import { cmdValidate } from "./cli/validateCommand.js";
 import { cmdValidateResults } from "./cli/validateResultsCommand.js";
 import { cmdRequeue } from "./cli/requeueCommand.js";
 import { cmdSynthesize } from "./cli/synthesizeCommand.js";
+import { cmdResynthesize } from "./cli/resynthesizeCommand.js";
 import { cmdCleanup } from "./cli/cleanupCommand.js";
 import { cmdQuota } from "./cli/quotaCommand.js";
 import { cmdDispatchStatus } from "./cli/dispatchStatusCommand.js";
@@ -93,6 +94,9 @@ async function main(argv) {
         case "synthesize":
             await cmdSynthesize(argv);
             return;
+        case "resynthesize":
+            await cmdResynthesize(argv);
+            return;
         case "cleanup":
             await cmdCleanup(argv);
             return;
@@ -119,7 +123,7 @@ async function main(argv) {
             return;
         default:
             console.error(`Unknown command: ${command}`);
-            console.error("Available commands: sample-run, advance-audit, next-step, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, cleanup, prepare-dispatch, merge-and-ingest, submit-packet, validate-result, quota, status, dispatch-status");
+            console.error("Available commands: sample-run, advance-audit, next-step, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, resynthesize, cleanup, prepare-dispatch, merge-and-ingest, submit-packet, validate-result, quota, status, dispatch-status");
             process.exitCode = 1;
     }
 }

package/dist/extractors/disposition.js

@@ -1,9 +1,16 @@
-import { isNodeModulesOrGit, isTmpPath, isBuildOutput, isVendorPath, isBinaryArtifact, isLicensePath, isLockfilePath, isLogPath, isDocPath, isGeneratedPath, isAuditArtifactPath, isGeneratedTestArtifactPath, isGeneratedInstallArtifactPath, isExamplesOrFixturesPath, normalizeExtractorPath, } from "./pathPatterns.js";
+import { isNodeModulesOrGit, isPackageManagerCachePath, isTmpPath, isBuildOutput, isVendorPath, isBinaryArtifact, isLicensePath, isLockfilePath, isLogPath, isDocPath, isGeneratedPath, isAuditArtifactPath, isAuditToolOutputArtifact, isGeneratedTestArtifactPath, isGeneratedInstallArtifactPath, isExamplesOrFixturesPath, normalizeExtractorPath, } from "./pathPatterns.js";
 function inferDisposition(path) {
     const normalized = normalizeExtractorPath(path);
     if (isNodeModulesOrGit(normalized)) {
         return { path, status: "excluded", reason: "node_modules or .git excluded by convention." };
     }
+    if (isPackageManagerCachePath(normalized)) {
+        return {
+            path,
+            status: "excluded",
+            reason: "Package-manager cache (npm _cacache/npm-cache) excluded by convention.",
+        };
+    }
     if (isTmpPath(normalized)) {
         return {
             path,
@@ -40,6 +47,13 @@ function inferDisposition(path) {
             reason: "Generated audit artifact.",
         };
     }
+    if (isAuditToolOutputArtifact(normalized)) {
+        return {
+            path,
+            status: "generated",
+            reason: "audit-tools pipeline output (findings/report) — a data deliverable, not source.",
+        };
+    }
     if (isGeneratedPath(normalized)) {
         return {
             path,

package/dist/extractors/pathPatterns.d.ts

@@ -24,6 +24,19 @@ export declare function isDocPath(normalized: string): boolean;
 export declare function isGeneratedInstallArtifactPath(normalized: string): boolean;
 export declare function isGeneratedTestArtifactPath(normalized: string): boolean;
 export declare function isAuditArtifactPath(normalized: string): boolean;
+/**
+ * Package-manager cache stores — npm's content-addressed `_cacache`, a nested
+ * `npm-cache`, or a local `.npm` — are dependency blobs, never the audited
+ * project's source. Smoke-test temp dirs can leave these inside the repo tree.
+ */
+export declare function isPackageManagerCachePath(normalized: string): boolean;
+/**
+ * The pipeline's own canonical machine contracts. When audit-tools audits itself
+ * (or any repo that checked one in) these are data deliverables, not source —
+ * auditing them yields only "this is JSON data" noise. The matching `*-report.md`
+ * renders are already handled as `doc_only` by `isDocPath`.
+ */
+export declare function isAuditToolOutputArtifact(normalized: string): boolean;
 export declare function isTestPath(normalized: string): boolean;
 export declare function isInterfacePath(normalized: string): boolean;
 export declare function isDataLayerPath(normalized: string): boolean;

package/dist/extractors/pathPatterns.js

@@ -22,6 +22,9 @@ const BINARY_EXTENSIONS = [
     ".otf",
     ".pdf",
     ".zip",
+    ".tgz",
+    ".tar",
+    ".gz",
 ];
 const LOCKFILE_NAMES = [
     "package-lock.json",
@@ -204,7 +207,31 @@ export function isGeneratedTestArtifactPath(normalized) {
     return splitSegments(normalized).some((segment) => segment.startsWith(".test-") && segment.endsWith("-artifacts"));
 }
 export function isAuditArtifactPath(normalized) {
-    return hasSegment(normalized, ".audit-tools");
+    return (hasSegment(normalized, ".audit-tools") ||
+        hasSegment(normalized, ".audit-artifacts"));
+}
+/**
+ * Package-manager cache stores — npm's content-addressed `_cacache`, a nested
+ * `npm-cache`, or a local `.npm` — are dependency blobs, never the audited
+ * project's source. Smoke-test temp dirs can leave these inside the repo tree.
+ */
+export function isPackageManagerCachePath(normalized) {
+    return (hasSegment(normalized, "_cacache") ||
+        hasSegment(normalized, "npm-cache") ||
+        hasSegment(normalized, ".npm"));
+}
+const AUDIT_TOOL_OUTPUT_BASENAMES = new Set([
+    "audit-findings.json",
+    "remediation-outcomes.json",
+]);
+/**
+ * The pipeline's own canonical machine contracts. When audit-tools audits itself
+ * (or any repo that checked one in) these are data deliverables, not source —
+ * auditing them yields only "this is JSON data" noise. The matching `*-report.md`
+ * renders are already handled as `doc_only` by `isDocPath`.
+ */
+export function isAuditToolOutputArtifact(normalized) {
+    return AUDIT_TOOL_OUTPUT_BASENAMES.has(baseName(normalized));
 }
 export function isTestPath(normalized) {
     const segments = splitSegments(normalized);

package/dist/io/artifacts.d.ts

@@ -2,7 +2,7 @@ import { cp, rm } from "node:fs/promises";
 import type { AuditResult, AuditTask, CoverageMatrix, RepoManifest, UnitManifest } from "../types.js";
 import type { AuditState } from "../types/auditState.js";
 import type { ArtifactMetadataManifest } from "../types/artifactMetadata.js";
-import type { AuditFindingsReport, FileDisposition, CriticalFlowManifest, GraphBundle, RiskRegister, SurfaceManifest } from "@audit-tools/shared";
+import type { AuditFindingsReport, FileDisposition, CriticalFlowManifest, GraphBundle, RiskRegister, SurfaceManifest, IntentCheckpoint } from "@audit-tools/shared";
 import type { SynthesisNarrativeRecord } from "../types/synthesisNarrative.js";
 import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
 import type { FlowCoverageManifest } from "../types/flowCoverage.js";
@@ -17,6 +17,7 @@ type ArtifactPayloadMap = {
     repo_manifest: RepoManifest;
     file_disposition: FileDisposition;
     auto_fixes_applied: unknown;
+    intent_checkpoint: IntentCheckpoint;
     unit_manifest: UnitManifest;
     graph_bundle: GraphBundle;
     surface_manifest: SurfaceManifest;
@@ -68,6 +69,7 @@ export declare const ARTIFACT_DEFINITIONS: {
     readonly repo_manifest: ArtifactDefinition<"repo_manifest">;
     readonly file_disposition: ArtifactDefinition<"file_disposition">;
     readonly auto_fixes_applied: ArtifactDefinition<"auto_fixes_applied">;
+    readonly intent_checkpoint: ArtifactDefinition<"intent_checkpoint">;
     readonly unit_manifest: ArtifactDefinition<"unit_manifest">;
     readonly graph_bundle: ArtifactDefinition<"graph_bundle">;
     readonly surface_manifest: ArtifactDefinition<"surface_manifest">;

package/dist/io/artifacts.js

@@ -34,6 +34,7 @@ export const ARTIFACT_DEFINITIONS = {
     repo_manifest: jsonArtifact("repo_manifest.json", "intake"),
     file_disposition: jsonArtifact("file_disposition.json", "intake"),
     auto_fixes_applied: jsonArtifact("auto_fixes_applied.json", "intake"),
+    intent_checkpoint: jsonArtifact("intent_checkpoint.json", "intake"),
     unit_manifest: jsonArtifact("unit_manifest.json", "analysis"),
     graph_bundle: jsonArtifact("graph_bundle.json", "analysis"),
     surface_manifest: jsonArtifact("surface_manifest.json", "analysis"),

package/dist/orchestrator/advance.js

@@ -3,6 +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 { runStructureExecutor, runDesignAssessmentExecutor, runDesignReviewAutoComplete, } from "./structureExecutors.js";
 import { runPlanningExecutor } from "./planningExecutors.js";
 import { runResultIngestionExecutor, runRuntimeValidationExecutor, runRuntimeValidationUpdateExecutor, runExternalAnalyzerImportExecutor, } from "./ingestionExecutors.js";
@@ -91,6 +92,11 @@ export async function advanceAudit(bundle, options = {}) {
                 run = await runIntakeExecutor(bundle, root);
                 break;
             }
+            case "intent_checkpoint_executor": {
+                const root = requireRoot(options.root, "intent_checkpoint_executor");
+                run = await runIntentCheckpointExecutor(bundle, root, options.since);
+                break;
+            }
             case "structure_executor":
                 // root is intentionally optional: present → buildGraphBundleFromFs, absent → manifest-only buildGraphBundle
                 run = await runStructureExecutor(bundle, options.root);

package/dist/orchestrator/dependencyMap.js

@@ -8,6 +8,13 @@ export const ARTIFACT_DEPENDENTS_MAP = {
     "tooling_manifest.json": [
         "repo_manifest.json",
     ],
+    "intent_checkpoint.json": [
+        "coverage_matrix.json",
+        "audit_tasks.json",
+        "audit_plan_metrics.json",
+        "review_packets.json",
+        "requeue_tasks.json",
+    ],
     "repo_manifest.json": [
         "file_disposition.json",
         "unit_manifest.json",

package/dist/orchestrator/designReviewPrompt.js

@@ -26,12 +26,17 @@ function summarizeGraph(bundle) {
         return "Dependency graph is empty.";
     return `Dependency graph: ${counts.join(", ")}.`;
 }
-function summarizeFlows(bundle) {
+function summarizeFlows(bundle, max = 15) {
     const flows = bundle.critical_flows?.flows ?? [];
     if (flows.length === 0)
         return "No critical flows identified.";
-    const lines = flows.map((flow) => `- ${flow.name}: ${flow.paths.length} files, concerns: ${flow.concerns.join(", ") || "none"}`);
-    return [`${flows.length} critical flows:`, ...lines].join("\n");
+    const shown = flows.slice(0, max);
+    const lines = shown.map((flow) => `- ${flow.name}: ${flow.paths.length} files, concerns: ${flow.concerns.join(", ") || "none"}`);
+    return [
+        `${flows.length} critical flows:`,
+        ...lines,
+        ...(flows.length > max ? [`  ... and ${flows.length - max} more`] : []),
+    ].join("\n");
 }
 function summarizeRisk(bundle) {
     const items = bundle.risk_register?.items ?? [];
@@ -78,12 +83,17 @@ function buildPrioritizedReadingList(bundle, maxUnits) {
         ...lines,
     ].join("\n");
 }
-function summarizeSurfaces(bundle) {
+function summarizeSurfaces(bundle, max = 20) {
     const surfaces = bundle.surface_manifest?.surfaces ?? [];
     if (surfaces.length === 0)
         return "No externally reachable surfaces identified.";
-    const lines = surfaces.map((surface) => `- ${surface.id} (${surface.kind}): ${surface.entrypoint}${surface.methods?.length ? ` [${surface.methods.join(", ")}]` : ""}`);
-    return [`${surfaces.length} surfaces:`, ...lines].join("\n");
+    const shown = surfaces.slice(0, max);
+    const lines = shown.map((surface) => `- ${surface.id} (${surface.kind}): ${surface.entrypoint}${surface.methods?.length ? ` [${surface.methods.join(", ")}]` : ""}`);
+    return [
+        `${surfaces.length} surfaces:`,
+        ...lines,
+        ...(surfaces.length > max ? [`  ... and ${surfaces.length - max} more`] : []),
+    ].join("\n");
 }
 function summarizeFiles(bundle) {
     const files = bundle.repo_manifest?.files ?? [];
@@ -100,13 +110,15 @@ function summarizeFiles(bundle) {
         .join(", ");
     return `${files.length} files (${langSummary}).`;
 }
-function formatDeterministicFindings(findings) {
+function formatDeterministicFindings(findings, max = 20) {
     if (findings.length === 0)
         return "No structural issues detected by deterministic analysis.";
-    const lines = findings.map((finding) => `- [${finding.severity}] ${finding.title}: ${finding.summary}`);
+    const shown = findings.slice(0, max);
+    const lines = shown.map((finding) => `- [${finding.severity}] ${finding.title}: ${finding.summary}`);
     return [
         `${findings.length} structural findings from deterministic analysis:`,
         ...lines,
+        ...(findings.length > max ? [`  ... and ${findings.length - max} more`] : []),
     ].join("\n");
 }
 export function renderDesignReviewPrompt(bundle, options = {}) {
@@ -118,7 +130,7 @@ export function renderDesignReviewPrompt(bundle, options = {}) {
     return [
         "# Project design review",
         "",
-        "You are reviewing the overall design of this project. The deterministic audit pipeline has already analyzed the codebase structure. Your job is to provide qualitative, big-picture design observations that static analysis cannot produce.",
+        "You are reviewing the overall design of this project. The deterministic audit pipeline has already analyzed the codebase structure. Your job is to provide qualitative observations in two distinct modes: contract assessment for inferred or existing project contracts, and conceptual design critique for broader architecture ideas that static analysis cannot produce.",
         "",
         "## Project context",
         "",
@@ -160,6 +172,15 @@ export function renderDesignReviewPrompt(bundle, options = {}) {
         "",
         prioritizedReadingList,
         "",
+        "### Contract assessment",
+        "",
+        "- Infer existing contracts from the repository artifacts and code you inspect: invariants, trust boundaries, preconditions, postconditions, data lifecycle obligations, and critical-flow guarantees.",
+        "- Attack those inferred contracts with concrete counterexamples. Report evidenced gaps where the code appears to rely on an invariant or boundary that is missing, unenforced, unclear, or uncovered for a critical flow.",
+        "- Use contract-assessment categories such as inferred_contract_gap, trust_boundary_gap, invariant_counterexample, and critical_invariant_coverage_gap when those best describe the finding.",
+        "- Stay observational: do not invent a new contract DSL, write a remediation plan, remediate code, or turn the audit into an implementation pipeline.",
+        "",
+        "### Conceptual design critique",
+        "",
         "- **Tool and library opportunities**: third-party tools, libraries, or frameworks that would improve the project. Concrete suggestions with rationale, not generic advice.",
         "- **Architecture pattern improvements**: structural changes that would improve extensibility, testability, or maintainability. Consider whether the current abstractions match the problem domain.",
         "- **Design simplification**: areas where the design is over-engineered or where simpler alternatives would work. Conversely, areas that are under-designed for their importance.",
@@ -174,7 +195,7 @@ export function renderDesignReviewPrompt(bundle, options = {}) {
         "{",
         '  "id": "DR-001",',
         '  "title": "short descriptive title",',
-        '  "category": "one of: tool_opportunity, architecture_pattern, design_simplification, integration, missing_capability",',
+        '  "category": "one of: inferred_contract_gap, trust_boundary_gap, invariant_counterexample, critical_invariant_coverage_gap, tool_opportunity, architecture_pattern, design_simplification, integration, missing_capability",',
         '  "severity": "one of: critical, high, medium, low, info",',
         '  "confidence": "one of: high, medium, low",',
         '  "lens": "architecture",',

package/dist/orchestrator/executors.js

@@ -14,6 +14,12 @@ export const EXECUTOR_REGISTRY = [
         obligation_ids: ["repo_manifest", "file_disposition"],
         description: "Create intake artifacts for repository discovery and disposition.",
     },
+    {
+        id: "intent_checkpoint_executor",
+        kind: "deterministic",
+        obligation_ids: ["intent_checkpoint_current"],
+        description: "Write intent_checkpoint.json with confirmed scope and intent.",
+    },
     {
         id: "structure_executor",
         kind: "deterministic",