audit-tools

One npm package shipping two independent code tools over a shared library. Each has its own CLI and host slash-command, and each is useful on its own:

• audit-code (/audit-code) — audits a repository/project and produces a findings report.
• remediate-code (/remediate-code) — implements changes from findings and/or free-form intent.

They compose but don't depend on each other: audit-code's findings are clean input to remediate-code, but you can run either alone. Audit a repo and stop. Or point remediate-code at a plain-English request with no audit in sight - or hand it audit findings and extra suggestions at the same time.

Each tool writes its results to .audit-tools/ as a machine contract (JSON) plus a human-readable render (markdown):

| Tool | Machine contract | Human render | |---|---|---| | audit-code | audit-findings.json | audit-report.md | | remediate-code | remediation-outcomes.json | remediation-report.md |

Philosophy

• The tool must be trustworthy even when the host agent is weak. Correctness is guaranteed by the tool, never by the host being careful or clever.
• Use mechanical, deterministic tools wherever one does the job as well as or better than a model.
• Use LLM judgment where it clearly lifts quality — bounded, scoped and recorded. The project is not "100% deterministic", and it is not trying to be.
• Whatever can be enforced in tooling must be, regardless of who does the work.
• Don't grade your own homework: anything important or complex gets an independent adversarial check that is allowed to refuse.
• Keep tasks tightly bound and well defined, so the gap between weak and strong models shrinks.
• Batch work into logical units of reasonable size — rigor balanced against token cost, not 100 agents for 100 files.
• Keep everything IDE-, provider-, model-, OS-, shell- and language-agnostic: outside the product contract or abstracted, never baked in. The host owns semantic execution; audit-tools detects repo structure and normalizes analyzer output into shared contracts, never forks planning per ecosystem.
• Auditing and remediating are not two tools — they are two cases of ONE logical core, drawn read-only or write-and-apply. The boundary between them is continuously being dissolved, and re-introducing it is the most persistent mistake made against this project; a difference between the two is a policy axis of the shared core, almost never a reason to fork it.
• Auditing produces findings, remediation consumes them and fixes. The machine contract is the source of truth; the human report is its render.
• Nothing runs to completion in a single call. Each invocation does a bounded, persisted piece of work, so a run is resumable, parallelizable and failure-isolated.
• Scale the process to the work — depth and granularity are dials on one pipeline, never a separate lighter path.
• Artifacts are continuity: staleness propagates along an explicit dependency map, never ad-hoc freshness checks.

Install

npm install -g audit-tools

This puts both audit-code and remediate-code on your PATH and deploys global slash-command assets for supported hosts (Claude, Codex, OpenCode, Antigravity, etc.). Running /audit-code inside a repo then bootstraps any remaining per-repo host files (e.g. VS Code's prompt/agent/instructions).

Usage

The tools are meant to be run as slash-commands inside a host agent. Just invoke the command—there are no provider, model, or quota flags. audit-tools plans bounded work and emits self-contained host workloads; the host chooses how to execute them, writes the bound result records, and returns them for strict validation and ingestion. The agent you're conversing with works through the persisted workflow and stops only for a real decision.

Audit a code base:

/audit-code

You'll confirm scope, depth, and which lenses to apply (security, correctness, reliability, data_integrity, etc.), then it runs autonomously to completion and leaves audit-findings.json + audit-report.md in .audit-tools/.

Every finding in the report is adversarially verified against current source by an independent reviewer before it's kept. The report opens with a triaged summary and drills down by severity:

(Illustrative sample — the counts and the file:line citation below are fabricated for the example, not a real finding.)

# Audit findings — verified & pruned

- Verified-real findings: 186 (of 204 extracted; 10 false, 8 uncertain)
- By severity: high 7 · medium 97 · low 78 · info 4
- By lens: tests 69 · maintainability 68 · correctness 24 · observability 17 · ...

## High (7)
### Citation-grounding retry leaves extracted plan completion marker
- Lens: correctness · Category: incorrect-state-transition · Confidence: high
- Summary: The promotion path writes the plan before running the citation-grounding
  backstop ... a later step treats the pipeline as complete, bypassing the retry.
- Affected: src/remediate/steps/contractPipeline.ts:540-548

Remediate issues or implement changes:

Just run:
/remediate-code
# auto-detects audit-findings.json and other sources of remediation targets

/remediate-code fix the stupid OAuth issues I keep running into
# turns your desires into structured plans, then remediates

/remediate-code implement ~/1337h4x/top-secret-plans.txt - also make a mobile app I can
use to track the progress of my nefarious machinations
# synthesizes structured findings + free-form feedback, plans out the whole refactor

It plans the changes, implements and verifies them, and lands the result - a commit, a PR / publish, whatever. You confirm scope and the closing action up front, and review a summary before anything is committed.

What to expect

• It drives itself. A single slash-command runs the full workflow; it pauses only for clarifications, and tries to front-load those questions so it can run uninterrupted.
• Runs are resumable. State persists to .audit-tools/ in the target repo, so an interrupted run picks up where it left off.
• The host owns execution. It can run independent work items in parallel using whatever native subagent or collaboration facilities are available in the current session.
• Effort scales to the work. Trivial work gets light review; risky or complex work gets deeper scrutiny.
• Results are untrusted input. Prompt bindings, file coverage, worktree identity, commit evidence, and test evidence are checked before host-produced work changes persisted state.

The pipelines, step by step

audit-code:

1. Understand the repo — deterministically maps files, public surfaces, the dependency graph, critical flows, and a risk register; runs available static analyzers and auto-fixes.
2. Confirm intent — you review the scope and pick the review lenses.
3. Map the subsystems — deterministically clusters the code into real subsystems by overlaying how it actually behaves (call/import, co-change, shared state) against how it's declared to be organized (directories, docs, comments), and flags where the two disagree: a tightly-coupled cluster no declared boundary owns, or a declared purpose smeared across the codebase. On a deeper review it then has an LLM extract and confirm each subsystem's charter — what it's stated to do versus what the code reveals it does — and surfaces the gaps, then triangulates any charter question still worth resolving into a clear yes/no before moving on.
4. Review the design — two parallel passes: a contract pass (invariants, boundaries, obligations) and a conceptual pass (philosophy, alternatives, better directions). On a deeper review it also runs a second-order adversarial pass over the whole codebase asking "is there a fundamentally better way to do this?", looping until a round turns up nothing new.
5. Plan — turns the risk register into bounded, prioritized review tasks and emits a complete, provider-neutral host workload.
6. Review through the host — the conversation host assigns the bounded items, then audit-tools validates and ingests the bound result records and deep-dives selectively.
7. Synthesize — consolidates everything into audit-findings.json + audit-report.md, then layers on a narrative (themes, executive summary, top risks).

The numbering is a conceptual grouping, not the literal execution sequence — the authoritative order is the PRIORITY array in src/audit/orchestrator/nextStep.ts, which interleaves some steps (e.g. deterministic subsystem clustering runs before the intent checkpoint).

remediate-code:

1. Intake — reads the findings and/or free-form intent, validates the input, and drafts a summary with any open questions.
2. Confirm intent — you confirm scope, answer open questions, and set the closing action (commit, push, open PR, publish, or halt).
3. Design the change — decomposes the work into modules, drafts a contract per module in parallel, detects and reconciles seams (where one module's output must match another's input), then derives obligations and a test plan. Riskier changes get an independent critic-and-judge pass.
4. Review the findings — presents every finding bucketed by how much of your judgment it needs (strategic / concrete / mechanical); you approve or decline each before anything proceeds to implementation.
5. Implement through the host — emits all eligible provider-neutral work items. The host performs the edits and returns prompt-bound commit and test evidence; audit-tools validates that evidence before accepting completion.
6. Close — previews the file list and commit message for your confirmation (unless pre-authorized), then runs the closing action and writes remediation-outcomes.json + remediation-report.md.

The numbering is a conceptual grouping, not the literal execution sequence — the authoritative order is decideNextStep in src/remediate/steps/nextStep.ts, which interleaves some steps.

CLI (backend / fallback)

The slash-commands are the product; the same engines are also directly runnable via CLI:

audit-code next-step        # advance an audit one step
remediate-code next-step    # advance a remediation one step

Add --root <repo> when running from outside the target repository.

Develop

TypeScript, Node 22+. From the repo root:

npm install     # always run first in a fresh clone/worktree
npm run build   # tsc → dist/
npm run check   # typecheck only
npm test        # build + test

Missing node_modules makes audit-tools/shared resolve a stale dist/, producing misleading "no exported member" type errors, so install before build/check/test.

See CLAUDE.md for architecture and design decisions, the specs in spec/, and the product/operator/contract guides in docs/audit-pkg/.

License

ISC