auditor-lambda 0.3.20 → 0.3.21

package/dist/supervisor/operatorHandoff.js

@@ -105,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,
             ]),
@@ -170,7 +168,7 @@ function renderMarkdown(handoff) {
             lines.push(`- ${command}`);
         }
         if (handoff.active_review_run) {
-            lines.push("- Use packet dispatch commands only when the conversation host exposes a callable subagent tool; otherwise follow the single-task fallback.");
+            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) {
@@ -233,9 +231,7 @@ 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,
         ]);

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
 
@@ -64,9 +64,10 @@ 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,
@@ -100,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
@@ -111,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.20",
+  "version": "0.3.21",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",

package/scripts/postinstall.mjs

@@ -56,6 +56,11 @@ const OPENCODE_AUDIT_BASH_PERMISSION = {
   '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',
@@ -63,25 +68,44 @@ const OPENCODE_AUDIT_BASH_PERMISSION = {
   '*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
@@ -127,6 +151,14 @@ function mergeOpenCodePermissionConfig(existingPermission, 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,
@@ -145,6 +177,7 @@ function renderOpenCodePermissionConfig() {
     read: 'allow',
     glob: 'allow',
     grep: 'allow',
+    external_directory: renderOpenCodeExternalDirectoryPermission(),
     edit: { ...OPENCODE_AUDIT_EDIT_PERMISSION },
     bash: { ...OPENCODE_AUDIT_BASH_PERMISSION },
   };

package/skills/audit-code/audit-code.prompt.md

@@ -1,55 +1,17 @@
 ---
-description: Autonomous local loop code auditing - advances deterministic audit state, delegates bounded review tasks, and ingests validated results
+description: Autonomous local loop code auditing - loads one backend-rendered audit step at a time
 argument-hint: [target-dir]
 allowed-tools: [Read, Bash, Glob, Grep, Agent]
 ---
 
-# `/audit-code` Execution Directive
+# `/audit-code` Loader
 
 You are the audit-code orchestrator for this conversation. The user-facing
-surface is only `/audit-code`; do not ask the user to choose backend commands,
-providers, models, paths, or batching strategy during normal operation.
+surface is `/audit-code`, but the backend owns every audit workflow branch.
 
-Your job is to advance the deterministic state machine, delegate bounded
-semantic review when the host supports subagents, and let the backend validate
-and ingest results mechanically.
+## Loader
 
-## Core Guardrails
-
-- Do not edit source files during semantic review. The deterministic
-  `auto_fixes_applied` executor may run formatter/remediation commands before
-  review; that is part of the backend workflow.
-- Do not manually merge audit results, manually update coverage, or manually
-  edit audit state.
-- Do not read result schemas or completed result payloads into context unless
-  a backend command fails and the error explicitly requires diagnosis.
-- Do not inspect individual subagent result files after dispatch. Validation
-  and ingestion are backend responsibilities.
-- Do not inspect the backend command catalog or try alternate subcommands to
-  bypass a blocked semantic-review handoff. In particular, do not run
-  `run-to-completion`, `synthesize`, `cleanup`, `requeue`, or direct
-  `ingest-results` while following this directive.
-- A report under `.audit-artifacts/` is not a completion signal while
-  `audit_state.status` is `"blocked"`. Present a report only after Step 5.
-- CRITICAL: Do not use your `Read` tool to read `entry.prompt_path` or JSON schemas into your own context window. The subagent will read them. Pass the path literally.
-- Prefer subagent dispatch for semantic review whenever the host exposes an
-  Agent/subagent tool.
-- Treat the user's `/audit-code` request as explicit authorization to launch
-  review subagents in parallel. Do not ask for a separate delegation request
-  before using available Agent/subagent tools.
-- Decide subagent support from the active toolset, not from shell commands or
-  backend provider names. A shell command named `agent`, an MCP prompt, or a
-  `local-subprocess` provider is not a host subagent facility.
-- Do not use `browser_subagent` for semantic review of source code unless the
-  task explicitly requires browser-based validation.
-- If the host cannot dispatch subagents, complete exactly one assigned review
-  task, run the provided ingestion command, then stop. The user can run
-  `/audit-code` again to continue from fresh context.
-
-## Step 1 - Advance Deterministic State
-
-First, make sure the repository has the minimal local assets required by the
-current host:
+First, make sure the repository has current local audit assets:
 
 ```bash
 audit-code ensure --quiet
@@ -61,141 +23,24 @@ Inside the `auditor-lambda` repository itself, use:
 node audit-code.mjs ensure --quiet
 ```
 
-Then run:
+Then ask the backend for exactly one next step:
 
 ```bash
-audit-code
+audit-code next-step
 ```
 
 Inside the `auditor-lambda` repository itself, use:
 
 ```bash
-node audit-code.mjs
+node audit-code.mjs next-step
 ```
 
-Parse only the command JSON envelope needed for routing:
-
-- `audit_state.status`
-- `handoff.active_review_run.run_id`
-- `handoff.artifacts_dir`
-- `handoff.active_review_run.task_path`
-- `handoff.active_review_run.prompt_path`
-- `handoff.active_review_run.pending_audit_tasks_path`
-- `handoff.active_review_run.audit_results_path`
-- `handoff.active_review_run.worker_command`
-
-If status is `"active"`, deterministic progress was made. Run Step 1 again.
-
-If status is `"complete"`, skip to Step 5.
-
-If status is `"blocked"` and the blocker is not semantic review, report the
-blocker verbatim and stop.
-
-If status is `"blocked"` for semantic review, continue to Step 2.
-
-## Step 2 - Dispatch Review Work
-
-Use this step only when the active toolset exposes a callable host subagent
-facility such as `Agent`, `Task`, or an equivalent built-in delegation tool.
-Do not try to discover subagent support by running shell commands.
-
-When that callable subagent facility exists, prepare a dispatch plan by default:
-
-```bash
-audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
-```
-
-Read only `<artifacts_dir>/runs/<run_id>/dispatch-plan.json`.
-
-In a single message, launch one Agent/subagent call per dispatch-plan entry:
-
-```text
-Agent({ description: entry.description, prompt: "Read and follow the audit instructions in: " + entry.prompt_path })
-```
-
-Do NOT use your `Read` tool to load `entry.prompt_path` into your context window. The subagent has its own context window and will read the file.
-
-If the host supports per-subagent model selection, use `entry.model_hint.tier`
-as a provider-neutral routing hint (`small`, `standard`, or `deep`). Map it to
-available host models without asking the user to choose model names. If model
-selection is unavailable, ignore the hint and dispatch normally.
-
-If the host supports per-subagent tool restrictions, give review subagents no
-Write tool and allow shell access only for the `audit-code submit-packet`
-command printed in their prompt.
-
-All subagent calls should be launched together. Wait for them to finish.
-
-Subagents own bounded semantic review. They must read only their prompt and
-assigned files, produce the requested `AuditResult[]`, pipe it to the
-`submit-packet` command in their prompt, retry up to 3 times if submission
-fails, and stop. The backend command validates and writes the packet-owned
-result artifacts. They must not use direct file writes, edit source files,
-remediate findings, create extra task results, run unrelated audits, or write
-the worker `result.json` control envelope.
-
-Then run:
-
-```bash
-audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
-```
-
-If `merge-and-ingest` exits non-zero, stop immediately and report the exact
-error. Do not improvise manual merging or state edits.
-
-Loop back to Step 1.
-
-If no callable host subagent facility exists, or a delegation attempt fails
-because the host does not provide such a tool, go directly to Step 3. Do not run
-`prepare-dispatch`, do not inspect generated packet prompts, and do not try
-alternate backend commands.
-
-## Step 3 - Single-Task Fallback
-
-Use this path only when the host cannot dispatch subagents.
-
-Allowed backend command in this step: the exact `worker_command` from the task
-file, after you have written the single-task result. Do not run `audit-code`,
-`run-to-completion`, `prepare-dispatch`, `merge-and-ingest`, `synthesize`,
-`validate`, or any other backend command as a substitute for the fallback.
-
-Read the generated single-task fallback prompt at
-`handoff.file_map.single_task_prompt` when present, otherwise
-`.audit-artifacts/dispatch/current-single-task-prompt.md`. That file is
-deterministically narrowed to the first pending task. If it is unavailable, read
-the current review prompt named by `handoff.active_review_run.prompt_path` or
-`.audit-artifacts/dispatch/current-prompt.md`, plus the matching task file
-needed to find `audit_results_path` and `worker_command`.
-
-Complete exactly one assigned review task. If a batch file lists multiple tasks,
-choose the first pending task by array order only; do not substitute a smaller
-or easier task. If that first task covers a large file, use targeted reads and
-searches within its assigned files instead of abandoning it. Read only that
-task's assigned files. Write one valid `AuditResult` object, wrapped in a JSON
-array, to `audit_results_path`.
-
-If the current review prompt says to produce results for every listed task, the
-single-task fallback overrides that wording for the top-level orchestrator:
-produce exactly one result for the first pending task only.
-
-Run the exact `worker_command` from the task file. Then stop and summarize that
-one bounded step. Do not loop into another semantic review task in the same
-conversation turn. Do not re-check audit state or read an audit report after the
-worker command.
-
-## Step 4 - Backend Failure Handling
-
-If `prepare-dispatch`, `merge-and-ingest`, or `worker_command` fails:
-
-- stop immediately
-- report the exact command and error output
-- do not manually create prompts, split tasks, merge results, edit state, or
-  remediate application code
-
-Invalid or missing subagent output is a blocker. It should not be silently
-merged or treated as automatic progress.
+Read the returned JSON only far enough to find `prompt_path`, then read and
+follow only that prompt. Do not read packet prompts, schemas, command catalogs,
+or handoff files unless the current step prompt explicitly instructs you to do
+so.
 
-## Step 5 - Present Results
+When a step prompt tells you to continue, run `audit-code next-step` again and
+follow only the newly returned `prompt_path`.
 
-When `audit_state.status` is `"complete"`, do not run the orchestrator again.
-Read `audit-report.md` and present the completed audit with work blocks first.
+Stop when the current step prompt tells you to stop.