auditor-lambda 0.3.19 → 0.3.21

package/dist/io/runArtifacts.js

@@ -10,6 +10,8 @@ const findingSchemaPath = join(packageRoot, "schemas", "finding.schema.json");
 const CURRENT_TASK_FILENAME = "current-task.json";
 const CURRENT_PROMPT_FILENAME = "current-prompt.md";
 const CURRENT_TASKS_FILENAME = "current-tasks.json";
+const CURRENT_SINGLE_TASK_FILENAME = "current-single-task.json";
+const CURRENT_SINGLE_TASK_PROMPT_FILENAME = "current-single-task-prompt.md";
 const CURRENT_SCHEMA_FILENAME = "audit-result.schema.json";
 const CURRENT_RESULTS_SCHEMA_FILENAME = "audit-results.schema.json";
 const CURRENT_FINDING_SCHEMA_FILENAME = "finding.schema.json";
@@ -63,6 +65,49 @@ async function writeDispatchSchemaFiles(artifactsDir) {
     await writeFile(join(dispatchDir, CURRENT_RESULTS_SCHEMA_FILENAME), await readFile(auditResultsSchemaPath, "utf8"), "utf8");
     await writeFile(join(dispatchDir, CURRENT_FINDING_SCHEMA_FILENAME), await readFile(findingSchemaPath, "utf8"), "utf8");
 }
+function renderSingleTaskFallbackPrompt(task, auditTask) {
+    const commandArgv = JSON.stringify(task.worker_command);
+    const lineCounts = auditTask.file_paths
+        .map((path) => `- ${path}: ${auditTask.file_line_counts?.[path] ?? 0} lines`)
+        .join("\n");
+    return [
+        "# audit-code single-task fallback",
+        "",
+        "Use this file only when the conversation host cannot dispatch subagents.",
+        "This prompt is generated deterministically from the first pending task.",
+        "",
+        `run_id: ${task.run_id}`,
+        `task_id: ${auditTask.task_id}`,
+        `unit_id: ${auditTask.unit_id}`,
+        `pass_id: ${auditTask.pass_id}`,
+        `lens: ${auditTask.lens}`,
+        `rationale: ${auditTask.rationale}`,
+        "",
+        "Assigned files and line counts:",
+        lineCounts,
+        "",
+        "Instructions:",
+        "1. Read only the assigned files above.",
+        "2. Produce exactly one AuditResult object for task_id above, wrapped in a JSON array.",
+        "3. Write that JSON array to audit_results_path.",
+        "4. Run worker_command exactly, then stop without checking audit state or reading a report.",
+        "",
+        `audit_results_path: ${task.audit_results_path}`,
+        `worker_command: ${commandArgv}`,
+        "",
+    ].join("\n");
+}
+async function writeSingleTaskFallbackFiles(artifactsDir, task, currentTasks) {
+    if (task.preferred_executor !== "agent" ||
+        !task.audit_results_path ||
+        !currentTasks ||
+        currentTasks.length === 0) {
+        return;
+    }
+    const firstTask = currentTasks[0];
+    await writeJsonFile(join(artifactsDir, "dispatch", CURRENT_SINGLE_TASK_FILENAME), firstTask);
+    await writeFile(join(artifactsDir, "dispatch", CURRENT_SINGLE_TASK_PROMPT_FILENAME), renderSingleTaskFallbackPrompt(task, firstTask), "utf8");
+}
 export async function writeWorkerTaskFiles(task, prompt, paths, artifactsDir, currentTasks, options = {}) {
     await mkdir(paths.runDir, { recursive: true });
     await writeJsonFile(paths.taskPath, task);
@@ -78,6 +123,7 @@ export async function writeWorkerTaskFiles(task, prompt, paths, artifactsDir, cu
     await writeJsonFile(join(artifactsDir, "dispatch", CURRENT_TASK_FILENAME), task);
     await writeFile(join(artifactsDir, "dispatch", CURRENT_PROMPT_FILENAME), prompt, "utf8");
     await writeJsonFile(join(artifactsDir, "dispatch", CURRENT_TASKS_FILENAME), currentTasks ?? []);
+    await writeSingleTaskFallbackFiles(artifactsDir, task, currentTasks);
     await writeDispatchSchemaFiles(artifactsDir);
 }
 export async function writeDispatchBatchFiles(artifactsDir, runs, currentTasks) {
@@ -121,6 +167,8 @@ export async function clearDispatchFiles(artifactsDir) {
         CURRENT_TASK_FILENAME,
         CURRENT_PROMPT_FILENAME,
         CURRENT_TASKS_FILENAME,
+        CURRENT_SINGLE_TASK_FILENAME,
+        CURRENT_SINGLE_TASK_PROMPT_FILENAME,
         CURRENT_SCHEMA_FILENAME,
         CURRENT_RESULTS_SCHEMA_FILENAME,
         CURRENT_FINDING_SCHEMA_FILENAME,

package/dist/prompts/renderWorkerPrompt.js

@@ -12,6 +12,7 @@ export function renderWorkerPrompt(task) {
             `Read: ${tasksPath}`,
             "Scope: review only the tasks listed in the Read file. Do not add tasks,",
             "edit source files, remediate findings, run unrelated audits, or write result_path.",
+            "Prefer host Read and Grep tools for source inspection. On native Windows, do not use Unix pipelines like `grep ... | head`; if shell search is unavoidable, use `Select-String` as a fallback.",
             "For each listed task: read the assigned file_paths under the specified lens,",
             "using targeted reads/searches where they give complete enough evidence without loading unrelated context,",
             "and emit exactly one AuditResult object with:",

package/dist/supervisor/operatorHandoff.js

@@ -11,6 +11,8 @@ const RUN_LEDGER_FILENAME = "run-ledger.json";
 const CURRENT_TASK_FILENAME = "current-task.json";
 const CURRENT_PROMPT_FILENAME = "current-prompt.md";
 const CURRENT_TASKS_FILENAME = "current-tasks.json";
+const CURRENT_SINGLE_TASK_FILENAME = "current-single-task.json";
+const CURRENT_SINGLE_TASK_PROMPT_FILENAME = "current-single-task-prompt.md";
 const AUDIT_TASKS_FILENAME = "audit_tasks.json";
 const RUNTIME_VALIDATION_TASKS_FILENAME = "runtime_validation_tasks.json";
 const BLOCKED_STATUS = "blocked";
@@ -103,9 +105,7 @@ function buildSuggestedCommands(artifactsDir, suggestedInputs, status, activeRev
         return [
             renderShellCommand([
                 "audit-code",
-                "prepare-dispatch",
-                "--run-id",
-                activeReviewRun.run_id,
+                "next-step",
                 "--artifacts-dir",
                 artifactsDir,
             ]),
@@ -121,7 +121,7 @@ function buildInteractiveProviderHint(status, providerName, sessionConfigPath, i
         return `Configuration error: Verify --root points to the intended repository root and that the tree contains auditable files.`;
     }
     const providerLabel = providerName ?? LOCAL_SUBPROCESS_PROVIDER_NAME;
-    return `Provider: ${providerLabel}. For automatic LLM review, configure an interactive provider in ${sessionConfigPath}.`;
+    return `Provider: ${providerLabel}. This is a deterministic semantic-review handoff, not a failed audit. Use host subagents when the active toolset provides them; otherwise use the single-task fallback and stop after the worker command. For automatic LLM review, configure an interactive provider in ${sessionConfigPath}; that is only needed for backend-launched review.`;
 }
 function renderMarkdown(handoff) {
     const lines = [
@@ -167,6 +167,9 @@ function renderMarkdown(handoff) {
         for (const command of handoff.suggested_commands) {
             lines.push(`- ${command}`);
         }
+        if (handoff.active_review_run) {
+            lines.push("- Use next-step so the backend renders either packet dispatch or single-task fallback after the host reports capabilities.");
+        }
     }
     if (handoff.active_review_run) {
         lines.push("", "Active review run:");
@@ -228,15 +231,15 @@ export function buildAuditCodeHandoff(params) {
     if (params.state.status === BLOCKED_STATUS && params.activeReviewRun) {
         handoff.quick_start = renderShellCommand([
             "audit-code",
-            "prepare-dispatch",
-            "--run-id",
-            params.activeReviewRun.run_id,
+            "next-step",
             "--artifacts-dir",
             params.artifactsDir,
         ]);
         handoff.file_map = {
             current_task: artifactPaths.current_task,
             current_prompt: artifactPaths.current_prompt,
+            single_task: join(params.artifactsDir, "dispatch", CURRENT_SINGLE_TASK_FILENAME),
+            single_task_prompt: join(params.artifactsDir, "dispatch", CURRENT_SINGLE_TASK_PROMPT_FILENAME),
             dispatch_plan: join(params.artifactsDir, "runs", params.activeReviewRun.run_id, "dispatch-plan.json"),
             audit_results: params.activeReviewRun.audit_results_path,
             final_report: join(params.root, "audit-report.md"),

package/docs/contracts.md

@@ -77,6 +77,23 @@ The backend stores resumable artifacts under `.audit-artifacts/`, including:
 Consumers should treat these as versioned JSON artifacts and validate them with
 `audit-code validate` rather than inferring state from filenames alone.
 
+## Step artifacts
+
+The conversation-first `/audit-code` prompt is a loader. It runs
+`audit-code next-step` and then follows only the returned step prompt. The
+backend writes the current step contract to:
+
+- `<artifacts_dir>/steps/current-step.json`
+- `<artifacts_dir>/steps/current-prompt.md`
+
+`current-step.json` uses `contract_version: "audit-code-step/v1alpha1"` and
+includes `step_kind`, `prompt_path`, `status`, `run_id`, `allowed_commands`,
+`stop_condition`, `repo_root`, `artifacts_dir`, and relevant `artifact_paths`.
+
+When semantic review is blocked, `next-step` first emits a `capability_check`.
+After the host reports `--host-can-dispatch-subagents true|false`, the backend
+renders exactly one review path: packet dispatch or the single-task fallback.
+
 ## Dispatch packets
 
 Packet dispatch preserves the existing `AuditTask` and `AuditResult`
@@ -92,13 +109,18 @@ Planning artifacts are shaped by:
 Normal packet flow:
 
 ```text
-audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
+audit-code next-step --host-can-dispatch-subagents true
+backend prepares dispatch-plan.json
 conversation launches one worker per dispatch-plan entry
 worker reads entry.prompt_path
 worker submits AuditResult[] through submit-packet
 audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
 ```
 
+`audit-code prepare-dispatch --run-id <run_id> --artifacts-dir
+<artifacts_dir>` remains available for compatibility and tests, but generic
+handoff fields point users and prompts to `next-step`.
+
 Packet artifacts:
 
 - `<artifacts_dir>/runs/<run_id>/dispatch-plan.json`

package/docs/operator-guide.md

@@ -43,7 +43,7 @@ Host-specific files may include:
 
 - Codex: managed `AGENTS.md` fallback guidance
 - Claude Desktop: project template, remote MCP connector, local MCP bundle
-- OpenCode: `opencode.json` with `/audit-code` slash command and auditor MCP server
+- OpenCode: `opencode.json` with auditor MCP server and permission wiring; the `/audit-code` command is global npm-installed state
 - VS Code/Copilot: prompt, custom agent, instructions, and `.vscode/mcp.json`
 - Antigravity: planning-mode and MCP-oriented guidance
 
@@ -57,14 +57,17 @@ ChatGPT-style project conversations are the intended product surface. Use
 default context.
 
 Codex should normally use the global skill seeded by the npm install plus
-repo-local `AGENTS.md` fallback guidance.
+repo-local `AGENTS.md` fallback guidance. The installed skill includes
+`agents/openai.yaml` metadata so Codex can keep the slash-list display aligned
+with the canonical `/audit-code` spelling.
 
 Claude Desktop is treated as an MCP-first host. Use the generated project
 template and local bundle artifacts when installing the integration.
 
-OpenCode uses `opencode.json` (generated by `audit-code ensure` or `audit-code
-install`) which registers the `/audit-code` slash command and the auditor MCP
-server together. VS Code uses repo-local prompt and MCP configuration files.
+OpenCode uses the global command seeded by `npm install -g auditor-lambda`.
+The generated project `opencode.json` should not define `command["audit-code"]`;
+it only wires the auditor MCP server and project permissions. VS Code uses
+repo-local prompt and MCP configuration files.
 
 Antigravity should be treated as a workflow-and-artifacts host until it has a
 stable project-local config surface. Use generated planning-mode guidance,
@@ -98,6 +101,7 @@ The wrapper:
 Useful fallback commands:
 
 ```bash
+audit-code next-step
 audit-code --single-step
 audit-code --results /path/to/audit_results.json
 audit-code --batch-results /path/to/results-dir
@@ -109,6 +113,11 @@ audit-code cleanup
 audit-code mcp
 ```
 
+`audit-code next-step` is the backend-rendered step engine used by the
+conversation prompt. It writes `.audit-artifacts/steps/current-step.json` and
+`.audit-artifacts/steps/current-prompt.md`, then the host should follow only
+that prompt.
+
 `audit-code validate` checks artifact shape, cross-artifact consistency,
 session config, and explicit provider readiness.
 

package/docs/product.md

@@ -148,9 +148,10 @@ Readiness should be judged through three checks:
 - field-trial quality: run real repositories through planning, validate
   artifacts, and use `audit_plan_metrics.json` to track packet count, weak
   packet count, average cohesion, merge edge kinds, and weak-packet samples
-- full-loop behavior: prove `prepare-dispatch`, worker review,
-  `submit-packet`, `merge-and-ingest`, selective deepening, runtime validation,
-  and final `audit-report.md` promotion in at least one real host flow
+- full-loop behavior: prove `next-step` capability routing, packet dispatch,
+  worker review, `submit-packet`, `merge-and-ingest`, selective deepening,
+  runtime validation, and final `audit-report.md` promotion in at least one
+  real host flow
 - release hygiene: keep `npm run verify:release`, linked smoke, packaged
   smoke, tarball preview, and Trusted Publishing green from a clean checkout
 

package/package.json

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

package/scripts/postinstall.mjs

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'url';
 const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const promptSourceFile = join(pkgRoot, 'skills', 'audit-code', 'audit-code.prompt.md');
 const skillSourceFile = join(pkgRoot, 'skills', 'audit-code', 'SKILL.md');
+const codexOpenAiAgentSourceFile = join(pkgRoot, 'skills', 'audit-code', 'agents', 'openai.yaml');
 
 function readRequiredSource(path, label) {
   if (!existsSync(path)) {
@@ -18,6 +19,15 @@ function readRequiredSource(path, label) {
   return readFileSync(path);
 }
 
+function readOptionalSource(path, label) {
+  if (!existsSync(path)) {
+    console.warn(`audit-code: ${label} source not found at ${path} - skipping optional install`);
+    return null;
+  }
+
+  return readFileSync(path);
+}
+
 function writeGeneratedFile(path, content) {
   const action = existsSync(path) ? 'updated' : 'installed';
   mkdirSync(dirname(path), { recursive: true });
@@ -32,8 +42,151 @@ function splitFrontmatter(text) {
   return { body: normalized.slice(match[0].length) };
 }
 
+const OPENCODE_AUDIT_EDIT_PERMISSION = {
+  '*': 'ask',
+  '.audit-code/**': 'allow',
+  '.audit-artifacts/**': 'allow',
+  'audit-report.md': 'allow',
+};
+
+const OPENCODE_AUDIT_BASH_PERMISSION = {
+  '*': 'ask',
+  'audit-code run-to-completion*': 'deny',
+  'audit-code synthesize*': 'deny',
+  'audit-code cleanup*': 'deny',
+  'audit-code requeue*': 'deny',
+  'audit-code ingest-results*': 'deny',
+  '*dist*index.js* run-to-completion*': 'deny',
+  '*dist*index.js* synthesize*': 'deny',
+  '*dist*index.js* cleanup*': 'deny',
+  '*dist*index.js* requeue*': 'deny',
+  '*dist*index.js* ingest-results*': 'deny',
+  '*audit-code.mjs* run-to-completion*': 'deny',
+  '*audit-code.mjs* synthesize*': 'deny',
+  '*audit-code.mjs* cleanup*': 'deny',
+  '*audit-code.mjs* requeue*': 'deny',
+  '*audit-code.mjs* ingest-results*': 'deny',
+  'audit-code': 'allow',
+  'audit-code ensure*': 'allow',
+  'audit-code next-step*': 'allow',
+  'audit-code prepare-dispatch*': 'allow',
+  'audit-code submit-packet*': 'allow',
+  'audit-code merge-and-ingest*': 'allow',
+  'audit-code validate*': 'allow',
+  '*audit-code.mjs': 'allow',
+  '*audit-code.mjs* ensure*': 'allow',
+  '*audit-code.mjs* next-step*': 'allow',
+  '*audit-code.mjs* prepare-dispatch*': 'allow',
+  '*audit-code.mjs* submit-packet*': 'allow',
+  '*audit-code.mjs* merge-and-ingest*': 'allow',
+  '*audit-code.mjs* worker-run*': 'allow',
+  '*audit-code.mjs* validate*': 'allow',
+  '*node* *auditor-lambda*dist*index.js* worker-run*': 'allow',
+  'node* .audit-code/install/run-mcp-server.mjs*': 'allow',
+  'node* ./.audit-code/install/run-mcp-server.mjs*': 'allow',
+  'git status*': 'allow',
+  'git diff*': 'allow',
+  'grep *': 'allow',
+  'Select-String *': 'allow',
+  'rm *': 'deny',
+};
+
+function replaceBackslashes(value) {
+  return value.replace(/\\/g, '/');
+}
+
+function externalDirectoryPattern(path) {
+  return `${replaceBackslashes(path).replace(/\/+$/u, '')}/**`;
+}
+
+function renderOpenCodeExternalDirectoryPermission() {
+  return {
+    [externalDirectoryPattern(pkgRoot)]: 'allow',
+    [externalDirectoryPattern(dirname(process.execPath))]: 'allow',
+  };
+}
+
+function objectValue(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+}
+
+function mergeOpenCodePermissionRule(existingRule, generatedRule, managedRules = {}) {
+  if (generatedRule && typeof generatedRule === 'object' && !Array.isArray(generatedRule)) {
+    const generatedObject = generatedRule;
+    const merged = {};
+    const existingObject =
+      existingRule && typeof existingRule === 'object' && !Array.isArray(existingRule)
+        ? existingRule
+        : {};
+
+    if (typeof existingRule === 'string') {
+      merged['*'] = existingRule;
+    } else {
+      merged['*'] = existingObject['*'] ?? generatedObject['*'] ?? 'ask';
+    }
+
+    for (const [key, value] of Object.entries(generatedObject)) {
+      if (key !== '*') merged[key] = value;
+    }
+    for (const [key, value] of Object.entries(existingObject)) {
+      if (key !== '*') merged[key] = value;
+    }
+    for (const [key, value] of Object.entries(managedRules)) {
+      merged[key] = value;
+    }
+
+    return merged;
+  }
+
+  return existingRule ?? generatedRule;
+}
+
+function mergeOpenCodePermissionConfig(existingPermission, generatedPermission) {
+  if (!existingPermission || typeof existingPermission !== 'object' || Array.isArray(existingPermission)) {
+    return generatedPermission;
+  }
+
+  return {
+    ...generatedPermission,
+    ...existingPermission,
+    read: generatedPermission.read,
+    glob: generatedPermission.glob,
+    grep: generatedPermission.grep,
+    external_directory: mergeOpenCodePermissionRule(
+      existingPermission.external_directory,
+      generatedPermission.external_directory,
+      generatedPermission.external_directory,
+    ),
+    edit: mergeOpenCodePermissionRule(
+      existingPermission.edit,
+      generatedPermission.edit,
+      OPENCODE_AUDIT_EDIT_PERMISSION,
+    ),
+    bash: mergeOpenCodePermissionRule(
+      existingPermission.bash,
+      generatedPermission.bash,
+      OPENCODE_AUDIT_BASH_PERMISSION,
+    ),
+  };
+}
+
+function renderOpenCodePermissionConfig() {
+  return {
+    read: 'allow',
+    glob: 'allow',
+    grep: 'allow',
+    external_directory: renderOpenCodeExternalDirectoryPermission(),
+    edit: { ...OPENCODE_AUDIT_EDIT_PERMISSION },
+    bash: { ...OPENCODE_AUDIT_BASH_PERMISSION },
+  };
+}
+
 function mergeOpenCodeGlobalConfig(existing, promptBody) {
   const parsed = existing ? JSON.parse(existing) : {};
+  const auditPermission = renderOpenCodePermissionConfig();
+  const existingAuditor = objectValue(objectValue(parsed.agent).auditor);
   return {
     ...parsed,
     command: {
@@ -47,12 +200,18 @@ function mergeOpenCodeGlobalConfig(existing, promptBody) {
         subtask: false,
       },
     },
+    permission: mergeOpenCodePermissionConfig(parsed.permission, auditPermission),
     agent: {
       ...(parsed.agent && typeof parsed.agent === 'object' && !Array.isArray(parsed.agent)
         ? parsed.agent
         : {}),
       auditor: {
+        ...existingAuditor,
         description: 'Read-heavy audit orchestration agent for the /audit-code workflow.',
+        permission: mergeOpenCodePermissionConfig(
+          existingAuditor.permission,
+          auditPermission,
+        ),
       },
     },
   };
@@ -75,23 +234,37 @@ if (!promptSource || !skillSource) {
 }
 
 const promptBody = splitFrontmatter(promptSource.toString('utf8')).body;
+const codexOpenAiAgentSource = readOptionalSource(codexOpenAiAgentSourceFile, 'Codex skill UI metadata');
 
 const installs = [
   {
     label: 'Claude command',
     path: join(homedir(), '.claude', 'commands', 'audit-code.md'),
+    sourcePath: promptSourceFile,
     content: promptSource,
   },
   {
     label: 'Codex skill',
     path: join(homedir(), '.codex', 'skills', 'audit-code', 'SKILL.md'),
+    sourcePath: skillSourceFile,
     content: skillSource,
   },
   {
     label: 'Codex prompt',
     path: join(homedir(), '.codex', 'skills', 'audit-code', 'audit-code.prompt.md'),
+    sourcePath: promptSourceFile,
     content: promptSource,
   },
+  ...(codexOpenAiAgentSource
+    ? [
+        {
+          label: 'Codex skill UI metadata',
+          path: join(homedir(), '.codex', 'skills', 'audit-code', 'agents', 'openai.yaml'),
+          sourcePath: codexOpenAiAgentSourceFile,
+          content: codexOpenAiAgentSource,
+        },
+      ]
+    : []),
 ];
 
 for (const install of installs) {
@@ -101,7 +274,7 @@ for (const install of installs) {
   } catch (err) {
     console.warn(`audit-code: could not install global ${install.label} (${err.message})`);
     console.warn(`  To install manually, copy from:`);
-    console.warn(`    ${install.label === 'Codex skill' ? skillSourceFile : promptSourceFile}`);
+    console.warn(`    ${install.sourcePath}`);
     console.warn(`  to:`);
     console.warn(`    ${install.path}`);
   }

package/skills/audit-code/SKILL.md

@@ -27,6 +27,11 @@ dispatch.
 If the host cannot delegate to subagents, the conversation orchestrator may
 complete exactly one assigned review task, ingest it through the provided backend
 command, then stop so the user can rerun `/audit-code` from fresh context.
+In that fallback path it should not prepare packet dispatch, probe alternate
+backend subcommands, synthesize reports, or choose a smaller task; the first
+pending task and the exact worker command are the boundary.
+The backend writes a deterministic single-task fallback prompt for that case so
+the orchestrator does not need to infer the first task from a broad batch prompt.
 
 Subagent fan-out belongs to the host agent runtime rather than to repo-local
 backend provider settings.

package/skills/audit-code/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "audit-code"
+  short_description: "Run the autonomous /audit-code repository audit workflow."
+  default_prompt: "Start /audit-code for this repository and continue until the audit completes or blocks for operator input."