/sc-audit — Autonomous Audit Orchestrator

Runs a full security audit of the target repository end-to-end in a single invocation. You (the model) drive every stage yourself — the deterministic Python steps AND the reasoning steps (the protocol model, the hypotheses, the PoCs) — in one continuous flow, without pausing for user input between stages. Report progress at each stage transition so the user can see what's happening, exactly like the understand skill.

Guiding principle: breadth of hypotheses, but only PoC-backed findings reach the report. Priority is low false positives.

Progress Reporting (REQUIRED — mirror understand)

At the start of every stage, print a status line:

[Stage N/7] <stage name>...

When a stage finishes, confirm in one line:

Stage N complete. <one-line result summary>

Example:

[Stage 1/7] Chunking the codebase...
Stage 1 complete. 13 chunks from 2 contracts, 10/10 functions covered.
[Stage 2/7] Modeling protocol & invariants...
Stage 2 complete. 7 invariants (2 critical), 1 privileged role.

Keep these lines short. They are the user's only window into a long run — never go silent for a whole stage.

Phase 0 — Pre-flight

1. Resolve the target. Parse $ARGUMENTS for the first non-flag token → the repo/dir to audit. If relative, resolve against the current working directory. Verify it exists and is a directory (test -d); if not, tell the user and STOP. If no path is given, use the current working directory. Call it TARGET.
2. Locate the pipeline driver. Use this skill's own scripts (installed copy):

   DRIVER="$HOME/.claude/skills/sc-audit/scripts/run_pipeline.py"
   [ -f "$DRIVER" ] || DRIVER="$(dirname "$0")/scripts/run_pipeline.py"
   DRIVER_DIR="$(dirname "$DRIVER")"   # sibling worker scripts live under ../sc-*/scripts

   The driver self-locates the sibling sc-* skills, so it works from any cwd.
3. Check Foundry. python "$DRIVER" "$TARGET" --status shows whether forge is available. If not, exploit PoCs will be marked needs-execution (differential math still runs); note this to the user but continue.
4. Honor --phase. If the user passed --phase X, run only that phase and stop (manual mode). Otherwise run the full autonomous flow below.

Announce: "I'm running the ProofHound audit pipeline on <TARGET> — 7 stages, every finding PoC-backed."

The autonomous run (do all of this, in order, without stopping)

[Stage 1/7] Chunking the codebase

Run the deterministic structural batch (chunk → signals → graph → math-scan):

python "$DRIVER" "$TARGET" --phase structural

Check the sc-ingest coverage gate in the output. If functions were missed, note it. Summarize: chunks, contracts, coverage.

[Stage 2/7] Modeling protocol & invariants

Produce <TARGET>/.audit/project-map.json — actors, trust model, privileged roles with by_design, money flow, and the protocol invariants INV-N (the backbone for low false positives). Choose by contract count:

• Few contracts: inline. Read the top entry points + signals.json and write the map yourself.
• Many contracts: fan-out per module:

  python "$DRIVER_DIR/../sc-map/scripts/batch_modules.py" "$TARGET/.audit" --size 3

  Spawn an sc-map-worker per map/batches/batch-NNN.json in parallel (partial maps → map/_partials/). Progress: Modeling module batch X/N. Then reconcile:

  python "$DRIVER_DIR/../sc-map/scripts/merge_maps.py" "$TARGET/.audit" --name "<Protocol>"

  Finally, do a SHORT inline pass to add cross-contract / protocol-level INV-N the per-module workers couldn't see (merge flags this in open_questions).

Summarize: invariant count by criticality, privileged roles.

[Stage 3/7] Extracting the math spec

Do the sc-spec work: read the docs/NatSpec and spec/math-candidates.json, then WRITE <TARGET>/.audit/spec/math-spec.json (+ reference models if docs give formulas). If there are no docs, set degraded_mode: true and emit property invariants. Promote any doc invariants into project-map.json. Summarize: formulas captured / degraded, references verified.

[Stage 4/7] Dependency graphs & routing

The graphs were built in Stage 1; now route hypotheses and build the Foundry workspace:

python "$DRIVER" "$TARGET" --phase route

Summarize: routed classes, deterministic seed count, workspace built (or degraded).

[Stage 5/7] Generating hypotheses

Do the sc-hypothesize reasoning on top of the seeds. Choose by size (this is what makes large protocols tractable):

• Small (≲ 40 routed functions): inline. Apply the routed audit-* checklists to the routed chunks yourself, then run the free-exploration pass.
• Large: fan-out to parallel workers (the understand-style scaling path):

  python "$DRIVER_DIR/../sc-hypothesize/scripts/batch_chunks.py" "$TARGET/.audit" --size 15

  For each batch-NNN.json, spawn an sc-hypothesis-worker subagent in parallel with that batch file. Report progress per batch: Analyzing batch X/N. When all finish, merge:

  python "$DRIVER_DIR/../sc-hypothesize/scripts/merge_hypotheses.py" "$TARGET/.audit"

  ($DRIVER_DIR = the dir of run_pipeline.py; the worker scripts are siblings.)
• Free-exploration (both paths): run an attacker-mindset analysis with NO checklist — prefer spawning subagent(s), optionally several with different personas (economic / griefer / MEV / governance) — targeting each critical/high INV-N with protocol-specific logic, composition, and edge cases. This is where novel bugs come from; spend real effort.
• Dedup + triage: set triage.decision on every hypothesis; reject unreachable/by-design/non-falsifiable ones WITH a reason (keep them on disk).

Summarize: hypotheses kept vs rejected, by source (and batch count if fan-out).

[Stage 6/7] Verifying with proofs

First consolidate + rank the hypotheses into a scored worklist (the orchestrator does this automatically in the verify phase; or run it explicitly):

python "$DRIVER_DIR/../sc-hypothesize/scripts/consolidate.py" "$TARGET/.audit"

hypotheses/consolidated.json → verify_worklist is the ranked list of candidate functions. Work it TOP-DOWN — author/execute PoCs for the highest-scoring candidates first so no high-value bug is left unverified when effort runs out. This is the fix for the "real bug buried in 177 hypotheses" failure.

Then author a PoC per kept hypothesis, in worklist order, and execute centrally. Choose by count:

• Few kept: inline. Write each prosecutor PoC (<TARGET>/.audit/verify/poc/H-*.t.sol) or differential candidate (verify/diff/H-*_candidate.py) plus the defender's mitigation check yourself.
• Many kept: fan-out the authoring (execution stays central):

  python "$DRIVER_DIR/../sc-verify/scripts/batch_verify.py" "$TARGET/.audit" --size 4

  For each verify/batches/batch-NNN.json, spawn an sc-verify-worker subagent in parallel to author its PoCs (no execution). Progress: Writing PoCs, batch X/N.
• Execute once (single verdict authority):

  python "$DRIVER" "$TARGET" --phase verify

  For a target that is its own Foundry project, PoCs may instead run in its own test/ so remappings/lib resolve. A finding is confirmed ONLY with a green proof.

Summarize: confirmed / rejected (and batch count if fan-out).

[Stage 7/7] Assembling the report

python "$DRIVER" "$TARGET" --phase report --name "<Protocol>"

Then polish the prose in <TARGET>/.audit/report/report.md (executive summary, code-specific recommendations). Summarize: confirmed findings by severity.

Final message to the user

Print a compact result:

• confirmed findings by severity,
• open items needing their input,
• invariant coverage (tested / total),
• the path to <TARGET>/.audit/report/report.md,
• and the honest limitations below.

Honest limitations (always surface)

• Heuristic Solidity parsing (no full AST): assembly, function pointers, using for, and unusual formatting can degrade chunking/graphs.
• The isolated Foundry workspace handles dependency-free targets; a real project with external libs runs PoCs best in its own test/.
• Checklists encode known classes; novel logic relies on the free-exploration pass — strong but not exhaustive. This is a high-precision force-multiplier for a human auditor, not a replacement.

Notes

• Run autonomously: do NOT stop and ask the user to run the next stage — you run it. The driver may print "NEXT (LLM gate)"; that is YOUR cue to do the reasoning step inline and continue, not to hand back to the user.
• Re-run safety: don't re-run structural/route after hypotheses are expanded (routing re-seeds). For a fresh audit, start clean.
• --phase X gives manual single-step control when the user wants it.