Audit Harness

Audit Harness — Generic Audit/Fix Loop

Goal: $ARGUMENTS

Step 0 — Initialize State

Generate a run_id: take the first 5 words of $ARGUMENTS, lowercase, replace spaces with hyphens, append today's date as -YYYYMMDD. Example: "ensure compute functions handle edge" → ensure-compute-functions-handle-edge-20260411.

Read .state/audit/state.json. If the file does not exist, create it:

{"version": 1, "runs": {}}

Check if runs[run_id] exists:

• If status === "done" → print "Run already completed." and stop.
• If status === "stalled" → print "Run stalled previously. Reset status to 'running' in state.json to retry." and stop.
• If status === "running" → resume from current global_cycle (skip to Step 2 if work_packages exist, otherwise Step 2 will re-plan).
• If not present → create a new entry:

  {
    "goal": "$ARGUMENTS",
    "status": "running",
    "created_at": "<ISO timestamp>",
    "global_cycle": 0,
    "global_clean_count": 0,
    "checkpoint_commit": null,
    "work_packages": [],
    "cycles": []
  }

Write state.json.

Step 1 — Checkpoint Git State

git add -A && git status --porcelain

If there are uncommitted changes, commit them:

git commit -m "audit-harness: checkpoint before run {run_id}"

Record the current HEAD SHA as checkpoint_commit in the run entry. Write state.json.

Step 2 — Spawn Planner (Plan Phase)

Spawn one agent using the prompt from .claude/skills/audit-harness/agents/planner.md.

Pass as context in the agent prompt:

• goal: The full $ARGUMENTS string
• mode: "plan"
• state: The full run entry JSON (so planner can see prior cycles if resuming)

Wait for the planner to complete. Find the line starting with PLANNER_RESULT: in its output. Parse the JSON after the prefix.

Expected shape:

{"action": "plan", "work_packages": [...]}

Write the work_packages array into the run entry (merge with existing if resuming — keep packages that are already "done"). Increment global_cycle. Write state.json.

Step 3 — Spawn Auditor Teams (Parallel)

Collect all work_packages where status !== "done" (i.e., clean_count < 2).

For each active package, spawn one agent using .claude/skills/audit-harness/agents/auditor.md.

Pass as context in each agent prompt:

• goal: $ARGUMENTS
• work_package: The full package object (id, area, description, scope_files)
• mode: "audit"
• prior_findings: The package's findings array (so auditor avoids re-reporting fixed issues)

Spawn ALL auditor agents in a SINGLE message (parallel execution).

Wait for all to complete. For each, find the AUDITOR_RESULT: line and parse the JSON.

Step 3b — Spawn Fixer Agents (Parallel)

Collect all packages where the auditor returned clean === false (has findings).

For each package with findings, spawn one agent using .claude/skills/audit-harness/agents/fixer.md.

Pass as context:

• goal: $ARGUMENTS
• work_package: The package object
• findings: The findings array from the auditor

Spawn ALL fixer agents in a SINGLE message (parallel execution).

Wait for all to complete. Parse each FIXER_RESULT: output.

Step 3c — Spawn Verification Auditors (Parallel)

For each package where the fixer applied at least one fix (applied === true), spawn one agent using .claude/skills/audit-harness/agents/auditor.md.

Pass as context:

• goal: $ARGUMENTS
• work_package: The package object
• mode: "verify"
• fixes_applied: The fixes array from the fixer output

Spawn ALL verification agents in a SINGLE message (parallel execution).

Wait for all to complete. Parse each AUDITOR_RESULT: output.