auditor-lambda 0.3.6 → 0.3.8

package/README.md

@@ -22,7 +22,28 @@ The canonical asset for editor and conversation integrations is:
 
 Packaged installs and repository checkouts both ship that prompt asset.
 
-The recommended zero-guess setup path is now:
+The intended user install is one global tool install:
+
+```bash
+npm install -g auditor-lambda
+```
+
+That makes `audit-code` available on `PATH`. During package install, the package
+also writes user-level command/skill assets for hosts we can seed safely, including
+the Claude command file and Codex skill bundle.
+
+After that, invoke `/audit-code` in a supported host. The prompt self-bootstraps
+the current repository by running:
+
+```bash
+audit-code ensure --quiet
+```
+
+That command writes or refreshes the repo-local assets only when they are missing
+or stale, then normal audit execution continues without manual paths, provider
+flags, or model-selection arguments.
+
+The explicit repair and compatibility setup path remains:
 
 ```bash
 audit-code install
@@ -36,9 +57,9 @@ That bootstraps repo-local `/audit-code` surfaces for the hosts we can automate
 - VS Code prompt, custom agent, Copilot instructions, and `.vscode/mcp.json`
 - Antigravity planning-mode guidance plus the shared repo-local MCP launcher
 
-Re-run the same `audit-code install` command whenever the packaged prompt or
-skill changes. It is the single supported refresh path for the shared
-`.audit-code/install/*` assets and every generated host surface.
+`audit-code ensure` refreshes those files automatically when the packaged prompt
+or skill changes. Use `audit-code install` or `audit-code ensure --force` when
+you intentionally want to rewrite every generated host surface on demand.
 
 After bootstrap, you can smoke-test the generated host assets and launcher from the repository root:
 
@@ -161,7 +182,8 @@ Optional backend config:
 ## Practical Guidance
 
 - use `/audit-code` in conversation as the canonical product surface
-- use `audit-code install` first when you want the lowest-friction repo bootstrap
+- install once with `npm install -g auditor-lambda`, then let `/audit-code` run `audit-code ensure --quiet` in each repository
+- use `audit-code install` when you want to repair or force-refresh repo-local host assets
 - use `audit-code prompt-path` to locate the packaged prompt asset
 - use `audit-code` from the repository root only when you need the repo-local backend fallback
 - use omitted provider or `local-subprocess` for the safest deterministic fallback behavior

package/audit-code-wrapper-lib.mjs

@@ -253,6 +253,7 @@ function printHelp({ usageName, preferredEntrypoint }) {
     '',
     'Helper commands:',
     '- prompt-path prints the absolute path to the canonical /audit-code prompt asset',
+    '- ensure lazily bootstraps repo-local /audit-code assets when they are missing or stale',
     '- install bootstraps /audit-code into supported repo-local host surfaces',
     '- verify-install smoke-tests the generated host assets and repo-local MCP launchers after install',
     '- mcp starts the local stdio MCP server for repo-local IDE integrations',
@@ -1952,7 +1953,188 @@ async function verifyInstalledBootstrap(argv) {
   process.exitCode = issueCount > 0 ? 1 : 0;
 }
 
-async function installBootstrap(argv) {
+async function readTextIfExists(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function detectBootstrapRefreshReason(root, host) {
+  const installManifestPath = join(
+    root,
+    '.audit-code',
+    'install',
+    INSTALL_MANIFEST_FILENAME,
+  );
+
+  if (!(await fileExists(installManifestPath))) {
+    return 'missing_install_manifest';
+  }
+
+  let installManifest;
+  try {
+    installManifest = JSON.parse(await readFile(installManifestPath, 'utf8'));
+  } catch {
+    return 'invalid_install_manifest';
+  }
+
+  if (installManifest?.contract_version !== 'audit-code-install/v1alpha1') {
+    return 'stale_install_manifest_contract';
+  }
+
+  const assetPaths = installManifest.asset_paths ?? {};
+  const hostCatalog = new Set(
+    (installManifest.hosts ?? []).map((entry) => entry.host),
+  );
+
+  for (const hostKey of getInstallHostKeys(host)) {
+    if (!hostCatalog.has(hostKey)) {
+      return `missing_host_surface:${hostKey}`;
+    }
+
+    const definition = INSTALL_HOST_DEFINITIONS[hostKey];
+    const requiredPathKeys = [
+      definition.primary_path_key,
+      ...definition.supporting_path_keys,
+    ];
+    for (const pathKey of requiredPathKeys) {
+      const targetPath = assetPaths[pathKey];
+      if (targetPath && !(await fileExists(targetPath))) {
+        return `missing_host_asset:${hostKey}:${pathKey}`;
+      }
+    }
+  }
+
+  const installedPrompt = await readTextIfExists(assetPaths.installedPromptPath);
+  if (installedPrompt === null) {
+    return 'missing_installed_prompt';
+  }
+  const sourcePrompt = await readFile(promptAssetPath, 'utf8');
+  if (installedPrompt !== sourcePrompt) {
+    return 'stale_installed_prompt';
+  }
+  const { body: sourcePromptBody } = splitFrontmatter(sourcePrompt);
+
+  const installedSkill = await readTextIfExists(assetPaths.installedSkillPath);
+  if (installedSkill === null) {
+    return 'missing_installed_skill';
+  }
+  const sourceSkill = (await readFile(skillAssetPath, 'utf8')).replace(/\r\n/g, '\n');
+  if (installedSkill.replace(/\r\n/g, '\n') !== sourceSkill) {
+    return 'stale_installed_skill';
+  }
+
+  for (const hostKey of getInstallHostKeys(host)) {
+    switch (hostKey) {
+      case 'codex': {
+        const codexSkill = await readTextIfExists(assetPaths.codexSkillPath);
+        if (codexSkill?.replace(/\r\n/g, '\n') !== sourceSkill) {
+          return 'stale_host_asset:codex:skill';
+        }
+        const codexPrompt = await readTextIfExists(assetPaths.codexPromptPath);
+        if (codexPrompt !== sourcePrompt) {
+          return 'stale_host_asset:codex:prompt';
+        }
+        break;
+      }
+      case 'opencode': {
+        const opencodeSkill = await readTextIfExists(assetPaths.opencodeSkillPath);
+        if (opencodeSkill?.replace(/\r\n/g, '\n') !== sourceSkill) {
+          return 'stale_host_asset:opencode:skill';
+        }
+        const opencodePrompt = await readTextIfExists(assetPaths.opencodePromptPath);
+        if (opencodePrompt !== sourcePrompt) {
+          return 'stale_host_asset:opencode:prompt';
+        }
+        const opencodeCommand = await readTextIfExists(assetPaths.opencodeCommandPath);
+        if (opencodeCommand === null) {
+          return 'missing_host_asset:opencode:command';
+        }
+        if (splitFrontmatter(opencodeCommand).body !== sourcePromptBody.trimStart()) {
+          return 'stale_host_asset:opencode:command';
+        }
+        break;
+      }
+      case 'vscode': {
+        const vscodePrompt = await readTextIfExists(assetPaths.vscodePromptPath);
+        if (vscodePrompt === null) {
+          return 'missing_host_asset:vscode:prompt';
+        }
+        if (splitFrontmatter(vscodePrompt).body !== sourcePromptBody.trimStart()) {
+          return 'stale_host_asset:vscode:prompt';
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  const launcherPath =
+    assetPaths.mcpLauncherPath ?? installManifest.mcp_server_launcher_path;
+  const launcher = launcherPath ? await readTextIfExists(launcherPath) : null;
+  if (launcher === null) {
+    return 'missing_mcp_launcher';
+  }
+  if (!launcher.includes('Unable to locate an audit-code executable')) {
+    return 'stale_mcp_launcher';
+  }
+
+  return null;
+}
+
+async function ensureBootstrap(argv) {
+  const host = (getFlag(argv, '--host') ?? DEFAULT_INSTALL_HOST).toLowerCase();
+  const root = resolve(getFlag(argv, '--root') ?? '.');
+  const quiet = hasFlag(argv, '--quiet');
+  const force = hasFlag(argv, '--force');
+  await assertDirectoryExists(root, 'Target repository root');
+
+  const reason = force
+    ? 'forced'
+    : await detectBootstrapRefreshReason(root, host);
+
+  if (reason) {
+    const installed = await installBootstrap(argv, { quiet: true });
+    const payload = {
+      status: 'ok',
+      action: 'installed',
+      reason,
+      host: installed.host,
+      repo_root: installed.repo_root,
+      install_manifest_path: installed.install_manifest_path,
+      mcp_server_launcher_path: installed.mcp_server_launcher_path,
+      host_count: installed.host_guidance.length,
+      file_count: installed.files.length,
+    };
+    if (!quiet) {
+      console.log(JSON.stringify(payload, null, 2));
+    }
+    return payload;
+  }
+
+  const payload = {
+    status: 'ok',
+    action: 'skipped',
+    reason: null,
+    host,
+    repo_root: root,
+    install_manifest_path: join(
+      root,
+      '.audit-code',
+      'install',
+      INSTALL_MANIFEST_FILENAME,
+    ),
+  };
+  if (!quiet) {
+    console.log(JSON.stringify(payload, null, 2));
+  }
+  return payload;
+}
+
+async function installBootstrap(argv, options = {}) {
   const host = (getFlag(argv, '--host') ?? DEFAULT_INSTALL_HOST).toLowerCase();
   const root = resolve(getFlag(argv, '--root') ?? '.');
   await assertDirectoryExists(root, 'Target repository root');
@@ -2221,49 +2403,49 @@ async function installBootstrap(argv) {
     results.push({ path: sessionConfigPath, mode: 'created' });
   }
 
-  console.log(
-    JSON.stringify(
-      {
-        host,
-        repo_root: root,
-        installed_prompt_path: installedPromptPath,
-        installed_skill_path: installedSkillPath,
-        install_guide_path: installGuidePath,
-        install_manifest_path: installManifestPath,
-        mcp_server_launcher_path: mcpLauncherPath,
-        source_prompt_path: resolve(promptAssetPath),
-        source_skill_path: resolve(skillAssetPath),
-        files: results,
-        slash_command_surfaces: {
-          vscode_prompt: assetPaths.vscodePromptPath,
-          opencode_command: assetPaths.opencodeCommandPath,
-        },
-        instruction_surfaces: {
-          agents: assetPaths.agentsInstructionsPath,
-          copilot_instructions: assetPaths.copilotInstructionsPath,
-        },
-        mcp_surfaces: {
-          vscode_workspace: assetPaths.vscodeMcpConfigPath,
-          opencode_project: assetPaths.opencodeConfigPath,
-          codex_setup: assetPaths.codexMcpSetupPath,
-          shared_launcher: mcpLauncherPath,
-          claude_desktop_dxt: assetPaths.claudeDesktopDxtPath,
-          claude_desktop_mcpb: assetPaths.claudeDesktopMcpbPath,
-          antigravity_planning_guide: assetPaths.antigravityPlanningGuidePath,
-        },
-        host_guidance: hostGuidance,
-        unsupported_hosts: [],
-        next_steps: [
-          'Open the repository in your preferred host and follow the matching host_guidance entry.',
-          `Open ${installGuidePath} for repo-local quick-start steps for Codex, Claude Desktop, OpenCode, VS Code, and Antigravity.`,
-          'Run `audit-code verify-install` from the repository root to smoke-test the generated launchers and host configs.',
-          'Use the shared MCP launcher as the source of truth for local stdio MCP registration across hosts.',
-        ],
-      },
-      null,
-      2,
-    ),
-  );
+  const payload = {
+    host,
+    repo_root: root,
+    installed_prompt_path: installedPromptPath,
+    installed_skill_path: installedSkillPath,
+    install_guide_path: installGuidePath,
+    install_manifest_path: installManifestPath,
+    mcp_server_launcher_path: mcpLauncherPath,
+    source_prompt_path: resolve(promptAssetPath),
+    source_skill_path: resolve(skillAssetPath),
+    files: results,
+    slash_command_surfaces: {
+      vscode_prompt: assetPaths.vscodePromptPath,
+      opencode_command: assetPaths.opencodeCommandPath,
+    },
+    instruction_surfaces: {
+      agents: assetPaths.agentsInstructionsPath,
+      copilot_instructions: assetPaths.copilotInstructionsPath,
+    },
+    mcp_surfaces: {
+      vscode_workspace: assetPaths.vscodeMcpConfigPath,
+      opencode_project: assetPaths.opencodeConfigPath,
+      codex_setup: assetPaths.codexMcpSetupPath,
+      shared_launcher: mcpLauncherPath,
+      claude_desktop_dxt: assetPaths.claudeDesktopDxtPath,
+      claude_desktop_mcpb: assetPaths.claudeDesktopMcpbPath,
+      antigravity_planning_guide: assetPaths.antigravityPlanningGuidePath,
+    },
+    host_guidance: hostGuidance,
+    unsupported_hosts: [],
+    next_steps: [
+      'Open the repository in your preferred host and follow the matching host_guidance entry.',
+      `Open ${installGuidePath} for repo-local quick-start steps for Codex, Claude Desktop, OpenCode, VS Code, and Antigravity.`,
+      'Run `audit-code verify-install` from the repository root to smoke-test the generated launchers and host configs.',
+      'Use the shared MCP launcher as the source of truth for local stdio MCP registration across hosts.',
+    ],
+  };
+
+  if (!options.quiet) {
+    console.log(JSON.stringify(payload, null, 2));
+  }
+
+  return payload;
 }
 
 async function installHostPrompt(argv) {
@@ -2316,6 +2498,11 @@ export async function runAuditCodeWrapper({
     return;
   }
 
+  if (argv[0] === 'ensure') {
+    await ensureBootstrap(argv.slice(1));
+    return;
+  }
+
   if (argv[0] === 'install') {
     await installBootstrap(argv.slice(1));
     return;

package/dist/cli.js

@@ -1504,6 +1504,9 @@ function buildDispatchModelHint(complexity) {
     if (complexity.tags.some((tag) => tag === "external_analyzer_signal" || tag.startsWith("external_tool:"))) {
         deepReasons.push("external_analyzer_signal");
     }
+    if (complexity.tags.includes("lens_verification")) {
+        deepReasons.push("lens_verification");
+    }
     if (deepReasons.length > 0) {
         return { tier: "deep", reasons: deepReasons };
     }
@@ -1680,15 +1683,31 @@ async function cmdPrepareDispatch(argv) {
                 : [];
         const taskSections = packetTasks.flatMap((task) => {
             const lensDef = lensDefs[task.lens];
+            const inputLines = task.inputs
+                ? Object.entries(task.inputs)
+                    .sort(([a], [b]) => a.localeCompare(b))
+                    .map(([key, value]) => `input.${key}: ${value}`)
+                : [];
+            const isLensVerification = task.tags?.includes("lens_verification") ?? false;
             return [
                 `### ${task.task_id}`,
                 `unit_id: ${task.unit_id}`,
                 `pass_id: ${task.pass_id}`,
                 `lens: ${task.lens}`,
+                ...(task.tags?.length ? [`tags: ${task.tags.join(", ")}`] : []),
+                ...inputLines,
                 `rationale: ${task.rationale}`,
                 "",
                 `Lens guidance: ${lensDef?.description ?? task.lens}`,
                 `Do NOT report: ${lensDef?.do_not_report ?? "N/A"}`,
+                ...(isLensVerification
+                    ? [
+                        "",
+                        "Lens verification mode: review the prior result summary in the rationale and use only targeted source checks.",
+                        "Do not redo every packet and do not write direct findings for this task.",
+                        "Return findings: [] plus verification metadata. Include followup_tasks only for bounded, specific re-review packets.",
+                    ]
+                    : []),
                 "",
             ];
         });
@@ -1735,6 +1754,13 @@ async function cmdPrepareDispatch(argv) {
             "  file_coverage [{path, total_lines}] - one entry per assigned file; use the line counts listed above",
             "  findings      [] or array of finding objects",
             "",
+            "Lens verification tasks:",
+            "  tasks tagged lens_verification must use findings: [] and include verification:",
+            "  {verified: boolean, needs_followup: boolean, concerns?: string[],",
+            "   coverage_concerns?: string[], confidence_concerns?: string[],",
+            "   followup_tasks?: AuditTask[]}.",
+            "  Follow-up AuditTask suggestions must stay bounded to files in this packet and use the same lens.",
+            "",
             "Each finding object:",
             "  id            unique ID, e.g. \"COR-001\"",
             "  title         short title",

package/dist/io/runArtifacts.js

@@ -93,13 +93,13 @@ export async function writeDispatchBatchFiles(artifactsDir, runs, currentTasks)
         "",
         `This batch launched ${runs.length} deferred review run(s).`,
         "Each run keeps its own task.json, prompt.md, result.json, and status.json under .audit-artifacts/runs/<run_id>/.",
-        "Use current-tasks.json for the combined task list, then inspect the per-run files below when you need exact prompts or result paths.",
+        "Use current-tasks.json for the combined task list. The per-run files below are operational references for launched workers; do not read per-run prompt or schema files unless debugging a failed dispatch.",
         "",
         "Runs:",
         ...runs.flatMap((run) => [
             `- ${run.run_id}`,
             `  task: ${run.task_path}`,
-            `  prompt: ${run.prompt_path}`,
+            `  prompt (worker-owned; do not read during normal orchestration): ${run.prompt_path}`,
             `  result: ${run.result_path}`,
             `  status: ${run.status_path}`,
             ...(run.audit_results_path

package/dist/orchestrator/internalExecutors.js

@@ -32,6 +32,7 @@ function appendSelectiveDeepeningTasks(params) {
         lineIndex,
         runtimeValidationTasks: params.bundle.runtime_validation_tasks,
         runtimeValidationReport: params.runtimeValidationReport ?? params.bundle.runtime_validation_report,
+        externalAnalyzerResults: params.bundle.external_analyzer_results,
     });
     if (selectiveDeepeningTasks.length === 0) {
         return { bundle: params.bundle, taskCount: 0, artifacts: [] };

package/dist/orchestrator/selectiveDeepening.d.ts

@@ -1,4 +1,5 @@
 import type { AuditResult, AuditTask } from "../types.js";
+import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
 import type { RuntimeValidationReport, RuntimeValidationTaskManifest } from "../types/runtimeValidation.js";
 export interface BuildSelectiveDeepeningTaskOptions {
     existingTasks?: AuditTask[];
@@ -6,9 +7,12 @@ export interface BuildSelectiveDeepeningTaskOptions {
     lineIndex?: Record<string, number>;
     runtimeValidationTasks?: RuntimeValidationTaskManifest;
     runtimeValidationReport?: RuntimeValidationReport;
+    externalAnalyzerResults?: ExternalAnalyzerResults;
     maxTasks?: number;
 }
 export declare function buildSelectiveDeepeningTasks(options: BuildSelectiveDeepeningTaskOptions): AuditTask[];
 export declare const selectiveDeepeningTestUtils: {
     DEEPENING_TAG: string;
+    LENS_VERIFICATION_TAG: string;
+    LENS_VERIFICATION_FOLLOWUP_TAG: string;
 };