auditor-lambda 0.3.2 → 0.3.4

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

@@ -1,22 +1,37 @@
 ---
-description: Autonomous local loop code auditing — steps the audit-code orchestrator and dispatches parallel subagents until the audit completes
+description: Autonomous local loop code auditing - advances deterministic audit state, delegates bounded review tasks, and ingests validated results
 argument-hint: [target-dir]
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent]
+allowed-tools: [Read, Write, Bash, Glob, Grep, Agent]
 ---
 
 # `/audit-code` Execution Directive
 
-**SYSTEM DIRECTIVE:** You are the autonomous audit orchestrator. Your job is to advance the state machine, dispatch parallel subagents for code review work, and loop until the audit is complete. Do not ask the user for confirmation between steps.
-
----
-
-## The Loop
-
-Repeat Steps 1–5 until the audit status is `"complete"`.
-
----
-
-### Step 1 — Advance the State Machine
+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.
+
+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.
+
+## 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.
+- Prefer subagent dispatch for semantic review whenever the host exposes an
+  Agent/subagent tool.
+- 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
 
 Run:
 
@@ -24,82 +39,97 @@ Run:
 audit-code
 ```
 
-_(Inside the `auditor-lambda` repo itself, use `node audit-code.mjs` instead.)_
+Inside the `auditor-lambda` repository itself, use:
 
-Parse the JSON output. Check `audit_state.status`:
+```bash
+node audit-code.mjs
+```
 
-| Status | Action |
-|--------|--------|
-| `"complete"` | Go to **Step 6** |
-| `"active"` | Deterministic progress was made — loop immediately back to Step 1 |
-| `"blocked"` | LLM work needed — continue to Step 2 |
+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`
 
-### Step 2 — Extract the Task IDs
+If status is `"active"`, deterministic progress was made. Run Step 1 again.
 
-Parse these fields directly from the Step 1 JSON output:
-- `run_id` — from `handoff.active_review_run.run_id`
-- `artifacts_dir` — from `handoff.artifacts_dir`
+If status is `"complete"`, skip to Step 5.
 
-_(If `audit_state.blockers` contains a message that requires operator input rather than code review, stop and report the blocker verbatim to the user.)_
+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 3 — Prepare the Dispatch Plan
+## Step 2 - Dispatch Review Work
 
-Run:
+When the host supports subagents, prepare a dispatch plan:
 
 ```bash
 audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
 ```
 
-Read `<artifacts_dir>/runs/<run_id>/dispatch-plan.json`. It is a JSON array where each entry has:
-- `task_id` — task identifier
-- `description` — short label for the Agent call
-- `output_path` — where the subagent writes its result
-- `prompt_path` — path to the complete subagent instructions file
+Read only `<artifacts_dir>/runs/<run_id>/dispatch-plan.json`.
 
----
+In a single message, launch one Agent/subagent call per dispatch-plan entry:
 
-### Step 4 — Dispatch All Subagents in Parallel
-
-**In a single message**, fire one `Agent` call per entry in `dispatch-plan.json`:
-
-```
+```text
 Agent({ description: entry.description, prompt: "Read and follow the audit instructions in: " + entry.prompt_path })
 ```
 
-All calls must be sent simultaneously — never await one before firing the next. This is the critical performance constraint. Wait for all to complete before proceeding.
-
-Each subagent reads its instruction file, reviews the assigned code, writes a validated JSON result to `output_path`, and self-validates. You do not need to inspect individual subagent output.
-
----
+All subagent calls should be launched together. Wait for them to finish.
 
-### Step 5 — Merge and Ingest
+Subagents own bounded semantic review. They must read only their prompt and
+assigned files, write exactly the requested audit result JSON to `output_path`,
+run the validation command in their prompt, retry up to 3 times if validation
+fails, and stop. They must not edit source files, remediate findings, create
+extra task results, run unrelated audits, or write the worker `result.json`
+control envelope.
 
-Run:
+Then run:
 
 ```bash
 audit-code merge-and-ingest --run-id <run_id> --artifacts-dir <artifacts_dir>
 ```
 
-Loop back to **Step 1**.
+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.
 
-### Step 6 — Present Results
+## Step 3 - Single-Task Fallback
 
-When `audit_state.status` is `"complete"`, stop the loop. Do **not** run the orchestrator again.
+Use this path only when the host cannot dispatch subagents.
 
-Read `audit-report.md` and present the completed audit to the user. Lead with the work blocks — they are the primary remediation handoff.
+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 only. Read only that task's assigned files. Write
+one valid `AuditResult` object, wrapped in a JSON array, to `audit_results_path`.
+
+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.
+
+## Step 4 - Backend Failure Handling
+
+If `prepare-dispatch`, `merge-and-ingest`, or `worker_command` fails:
 
-## Edge Cases
+- stop immediately
+- report the exact command and error output
+- do not manually create prompts, split tasks, merge results, edit state, or
+  remediate application code
 
-**Large task warnings:** `prepare-dispatch` warns about tasks exceeding ~1500 lines. If a subagent hits a quota limit and fails to produce output, `merge-and-ingest` excludes it silently — those tasks remain pending and are picked up in the next loop iteration. No manual intervention needed.
+Invalid or missing subagent output is a blocker. It should not be silently
+merged or treated as automatic progress.
 
-**Failed validation:** Subagents self-validate and retry up to 3 times before finishing. `merge-and-ingest` excludes any results that still lack required fields and writes `failed-tasks.json`. Those tasks are requeued automatically in the next cycle.
+## Step 5 - Present Results
 
-**Command failures:** If `prepare-dispatch` or `merge-and-ingest` exits non-zero, **STOP immediately** and report the exact error output to the user. Do NOT improvise manual dispatch, manually split tasks, manually create directories, manually construct prompts, or manually merge results. These scripts are the canonical mechanism — operating without them produces incorrect output. Fix the underlying issue and re-run the failed command.
+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.