Godaudits

---
name: godaudits
description: "Audit a codebase end to end and emit validated JSON plus remediation MDX, or review one diff for non-obvious blast radius with explicit safety facts and a compiled merge proof gate. godaudits fingerprints the repository, detects six project forms, validates Pillars 1.1 and arc-ready artifacts, evaluates 437 checks across 18 domains with pass/fail/unknown/not-applicable outcomes, records hashed secret-safe evidence, covers OWASP Web Top 10:2025, adversarially refutes findings, computes scores with coverage and risk caps, and renders optional SARIF. Includes focused, full, re-audit, plan-aware, and change-safety modes. Static mode never runs the app, tests, live systems, network, or models. Use for audits, health checks, due diligence, production readiness, remediation, blast-radius reviews, and pre-merge safety. Refuses stale evidence, invented citations, secrets, unsupported regulatory claims, double-billing, unproven merge safety, and Critical or High findings without executable tasks."
license: MIT
metadata:
  version: "2.18.0"
  author: aihxp
  homepage: https://github.com/hannsxpeter/godaudits
---

> Invocation: `/godaudits` in Claude Code, Cursor, VS Code, Zed, and Factory; `$godaudits` in Codex; `@godaudits` in Windsurf; auto-triggered elsewhere. Treat text after the command as a path, focus, or constraint. The runtime lives beside this file at `runtime/godaudits.js`; use the installed `godaudits` command when available, otherwise run that file with Node 22 or newer.

# godaudits

Audit everything after anything. godaudits 2.18 is an evidence-first audit system, not only an audit prompt. The domain modules carry judgment. The bundled zero-dependency runtime carries inventory, form and overlay detection, Pillars 1.1 routing, arc-ready artifact validation, check-catalog compilation, state initialization, freshness validation, score computation, rendering, SARIF export, re-audit diffs, remediation wayfinding, and evaluation metrics.

The machine source of truth is `.godaudits/AUDIT.json`. It records every applicable check, including clean and unknown checks. `.godaudits/AUDIT.mdx` is a generated standalone report and remediation handoff. `.godaudits/AUDIT.sarif` is optional integration output. Never hand-edit derived scores or counts.

godaudits remains the mirror of godplans. Audit check `A-SEC-3` verifies plan requirement `R-SEC-3`. In plan-aware mode, findings carry both ids and plan drift is audited in the owning domain.

## Ground rules (non-negotiable)

1. **Static is the safe default.** Static mode reads source and git metadata, writes only under `.godaudits/`, and never runs the application, tests, migrations, live systems, network requests, or model calls.
2. **Stronger evidence requires explicit authority.** Sandbox evidence is allowed only when the user explicitly authorizes execution in a disposable environment with outbound network disabled and no production credentials. Connected evidence is allowed only through explicitly authorized read-only CI, observability, database-metadata, or tracker access. Record the capability in `audit.capabilities`.
3. **Every check gets an outcome.** Applicable checks are `pass`, `fail`, or `unknown`; conditional checks may be `not-applicable` with evidence. Uninspected is `unknown`, never `pass`. Unknown checks reduce coverage and cap the verdict.
4. **Evidence over assertion.** Every pass, failure, and strength references evidence. Source evidence carries path, line, quote, and content hash. Absence evidence carries the exact search, scope, and zero-hit result. Tool and runtime evidence carry command, tool version, and result provenance.
5. **Secrets never enter the report.** Mask credential values and store only a one-way fingerprint. A live secret may be a Critical finding; the secret itself is never quoted into JSON, MDX, SARIF, chat, or logs.
6. **The substitution test.** A finding or recommendation that remains plausible after swapping in a near-equivalent repository is too generic and is deleted.
7. **Root causes, not leaves.** Cluster repeated symptoms under the root cause and list member sites in evidence.
8. **One owner per concern.** Apply the ownership map in `references/intake.md`. Other domains cross-reference the owning finding and do not score it again.
9. **Independent refutation.** Re-open every candidate citation, trace the relevant execution path, search for guards and framework defaults, and try to disprove the finding. Drop refuted candidates. Weaken or mark unresolved cases Tentative.
10. **Scores are compiled.** Use the catalog weights and runtime compiler. Do not type a score based on judgment. Coverage caps and Critical caps apply after weighted computation.
11. **Every Critical and High closes.** Each open Critical or High finding has a reciprocal remediation task with exact files, acceptance conditions, check ids, and a verification command.
12. **The artifacts stand alone.** Another agent must be able to remediate from AUDIT.json and AUDIT.mdx without this chat.
13. **Compliance is standing.** Load `references/compliance.md` and the applicable policy pack. Hard-stop only prohibited core purposes. Do not turn ambiguous intent into a refusal without one clarifying question.
14. **Copy signals are leads.** Reader-facing phrase matches identify lines for product, UX, or launch review. They do not establish AI authorship or a writing defect without a source read, and broad technical words never fail by presence alone.
15. **Change safety is proof, not prose.** A blast-radius review records one or two repository-specific safety facts, follows contracts and lifecycle edges beyond symbol search, and cannot pass its merge gate until every fact plus the cheapest before-merge reproduction reaches executable proof. Unproved facts say unproven.

## Dynamic verification (opt-in)

Static is the default and never runs the product. When the user explicitly authorizes a disposable runtime environment (ground rule 2), godaudits may add a dynamic verification pass that CONFIRMS or REFUTES its behavioral findings against the running app rather than trusting static inference alone. Behavioral findings are the class static reading can suspect but not prove: race conditions and TOCTOU, dead controls that are stored but never read, lifecycle transitions that free a resource early, authorization gaps on a non-primary caller path, and accessibility or consent behavior that only appears at runtime. Each such finding carries a runtime-verification handoff (a route or request sequence with the expected-versus-actual outcome) that an authorized harness runs: the Godpowers `god-browser-tester` (headless browser against a runtime URL) or a project Playwright suite. Runtime confirmation upgrades a Tentative finding to Firm or Certain; refutation drops it. Dynamic verification never runs automatically, never touches production, and its results are recorded as runtime evidence with provenance.

The runtime supports this handoff directly: `godaudits verify-runtime plan AUDIT.json` emits a probe manifest for the behavioral findings, the authorized harness executes the probes and produces a results file, and `godaudits verify-runtime apply AUDIT.json RESULTS.json` folds confirmed and refuted dispositions into a verification report that a re-audit applies. Because AUDIT.json scores are compiled, dispositions are applied on re-audit, never hand-edited.

Change-safety execution follows the same authority boundary but uses a separate artifact. `godaudits blast-radius plan` reads only Git metadata and diffs. An authorized external harness produces level 4 executable or level 5 running-app results, and `godaudits blast-radius apply` imports them without executing their commands. Read `references/change-safety.md` before this workflow.

The runtime serializes independent refutation (ground rule 9) the same way: `godaudits refute plan AUDIT.json` emits one brief per open Critical or High finding carrying the claim, its citation, the owning check, and the expected behavior, with the originating reasoning stripped so a separate pass forms its own view; `godaudits refute apply AUDIT.json RESULTS.json` folds the verdicts (refuted, weakened, no-refutation) into a report a re-audit applies. This extends Phase 4, it does not replace it, and it adds no evidence to a finding: a refuted finding's guard citation may support a strength or the check's pass, never the finding it refuted.

Second opinion: the check catalog has a structural ceiling, it verifies control presence. To find what it would miss, an authorized run may add an unconstrained pass that reads the code fresh, without the catalog's framing, hunting behavioral defects (races, dead controls, early transitions, authorization gaps on non-primary paths) and feeding novel findings back as candidates. Verify each with the same evidence and refutation discipline before recording it. Apply the pass whole, never a sampled subset. Before recording a candidate as novel, search the catalog for a check that already owns the claim: if one exists the candidate is not a discovery but evidence against that check, and it updates that check's outcome in place. A surviving candidate must still route to a weighted owning check in its own domain. A survivor that maps to an already-failing check is a distinct root cause recorded under the ownership map, never a deletion of the existing finding.

## Runtime commands

Commands below use `godaudits`. When it is not on PATH, replace it with `node <skill-directory>/runtime/godaudits.js`.

```bash
godaudits doctor
godaudits evidence . --output .godaudits/EVIDENCE.json
godaudits pillars . --task "TASK" --target PATH
godaudits init --name PROJECT --scale SCALE --profile PROFILE --applicable security,build,repo --budget medium --evidence .godaudits/EVIDENCE.json --output .godaudits/AUDIT.json
godaudits validate .godaudits/AUDIT.json --repo . --require-fresh-evidence --write
godaudits render .godaudits/AUDIT.json --output .godaudits/AUDIT.mdx
godaudits sarif .godaudits/AUDIT.json --output .godaudits/AUDIT.sarif
godaudits import-sarif scanner.sarif --output .godaudits/TOOL-EVIDENCE.json
godaudits import-tool semgrep.json --tool semgrep --command "semgrep scan --json ." --output .godaudits/TOOL-EVIDENCE.json
godaudits diff .godaudits/archive/AUDIT-v1.json .godaudits/AUDIT.json
godaudits evaluate .godaudits/AUDIT.json expected.json
godaudits blast-radius plan . --base BASE_REV --head HEAD_REV --fact "SAFETY FACT" --verify "COMMAND" --output .godaudits/CHANGE-REVIEW.json
godaudits blast-radius validate .godaudits/CHANGE-REVIEW.json
godaudits blast-radius apply .godaudits/CHANGE-REVIEW.json .godaudits/CHANGE-RESULTS.json --output .godaudits/CHANGE-REVIEW.json
godaudits blast-radius render .godaudits/CHANGE-REVIEW.json --output .godaudits/CHANGE-REVIEW.mdx
godaudits blast-radius evidence .godaudits/CHANGE-REVIEW.json --start 1000 --output .godaudits/CHANGE-EVIDENCE.json
godaudits wayfind .godaudits/AUDIT.json
```

The runtime never decides whether a signal is a finding. `EVIDENCE.json` contains deterministic inventory leads and absence records. `import-sarif` and `import-tool` convert SARIF, Semgrep, ast-grep, Gitleaks, and OSV-Scanner results into secret-safe tool evidence without creating findings. Non-SARIF adapters require the producing command and a tool version when the report does not embed one. Domain passes trace, interpret, and refute both sources.

## Change-safety review (separate workflow)

When the user asks what a diff could break, whether a change is safe, or for its blast radius, read `references/change-safety.md` and use the `blast-radius` commands. This workflow does not initialize, score, or mutate AUDIT.json.

1. Read the diff and state one or two load-bearing safety facts. The deterministic runtime never invents them.
2. Name the cheapest test or reproduction that fails loudly if the change is unsafe.
3. Run `blast-radius plan` with immutable base and head revisions. Add `--audit AUDIT.json` when existing findings should be joined by changed evidence path.
4. Trace the emitted leads across public contracts, storage, dependency source and patches, configuration keys, serialization, cross-language readers, lifecycle ordering, caches, generated artifacts, and non-primary entry points. Leads are not risks.
5. Record confirmed risks with separate likelihood and consequence. Record cleared risks with proof and the condition that invalidates the clearance.
6. Under explicit sandbox or connected authority, run the smallest real-code proof for each fact and the before-merge command. Import the result with `blast-radius apply`.
7. Validate and render. `blocked` means a refuted fact, failed reproduction, or open High or Critical consequence risk. `unproven` means any fact or the reproduction stopped below level 4. Only `pass` is merge-ready.
8. When a re-audit needs the proof, export it with `blast-radius evidence`. The export creates evidence leads only; the owning domain still traces, refutes, and updates its existing checks.

Proof levels are assertion (1), source citation (2), failure path shown unreachable (3), executable proof against shipped code (4), and running-app reproduction (5). Confidence never substitutes for proof level. CHANGE-REVIEW.json is the machine source of truth and CHANGE-REVIEW.mdx is generated.

## Method

Run every phase in order. A phase that does not apply still gets a disposition in the audit trail.

### Phase 0: Orient and select capabilities

Read the mode-detection section of `references/intake.md`.

- `.godaudits/AUDIT.json` exists -> re-audit.
- Source exists and no audit state exists -> fresh audit.
- No source -> refuse and point to godplans.
- `.godplans/PLAN.mdx` exists -> add the plan-aware overlay.
- User names domains -> focused audit. Every domain still gets an applicability row; domains outside the requested focus are excluded with that exact reason.
- No domain scope named -> focused audit is still the default. Select the smallest set justified by the requested concern, project form, and highest-risk evidence leads. Record every other domain as excluded with that scope reason.
- Full audit -> only when the user explicitly requests full-project due diligence or equivalent breadth. Pass `--applicable all --budget full` and ensure every domain module fits the available context.

Record the commit, runtime and pack versions, selected capabilities, tool versions, assumptions, and constraints. Run `godaudits doctor`. If Node is unavailable, continue manually but mark deterministic validation unavailable and every affected check unknown. Never claim full coverage in degraded mode.

### Phase 1: Compliance gate

Read `references/compliance.md` and the selected policy pack under `policies/`.

- Prohibited core purpose -> name the policy category and stop.
- Legitimate product with policy-risk code -> continue and inject `F-CMP-n` findings with mandatory tasks.
- Pass -> record one line and continue.

Policy packs are versioned evidence, not timeless truth. On compliance-sensitive audits, verify the current primary policy text when network access is authorized. Otherwise record the policy snapshot and confidence.

### Phase 2: Deterministic intake and evidence

Read `references/intake.md` fully. Run the static fingerprint command before domain judgment. Review `.godaudits/EVIDENCE.json`; it inventories manifests, lockfiles, languages, files and hashes, high-signal source locations, absence evidence, six-form routing, product and industry overlays, regulatory candidates, arc-ready artifacts, Pillars 1.1 state, compatibility archetype inference, and limitations. When any `copy-*` signal exists, read `guides/copy-signals.md` before routing it. Treat Pillars paths as repository-relative. Arc artifact freshness uses Git history when available and an explicit filesystem fallback otherwise; prepublication may bind hardening by content SHA-256 or Git revision.

Complete the primary and secondary project forms, product and industry overlays, regulatory candidates, compatibility archetype, scale calibration, risk profile, applicability matrix, ownership map, and assumptions. A regulatory candidate never establishes legal applicability without verification. Use `balanced` by default, `security-critical` for regulated data, money, identity, privileged actions, or multi-tenancy, `growth` for public conversion and visibility surfaces, and `library` for libraries and developer tools. Ask at most one batch of 0 to 3 questions only when the repository cannot answer and the answer changes applicability or severity.

Initialize AUDIT.json after intake. For focused audits, pass the comma-separated applicable domains instead of `all`. Medium is the default budget: evaluate screening checks and leave every deep-trace check unknown in the complete selected-domain ledger. Unknowns lower coverage. Full budget selects both tiers and is explicit.

### Phase 3: Domain passes and check ledger

For each applicable domain, in this order, read its module at the moment of use and evaluate every listed check:

| Order | Domain | Module |
|---|---|---|
| 1 | Product reality | `references/product.md` |
| 2 | Architecture | `references/architecture.md` |
| 3 | Stack | `references/stack.md` |
| 4 | Database | `references/database.md` |
| 5 | Security | `references/security.md` |
| 6 | LLM integration | `references/llm.md` |
| 7 | UX | `references/ux.md` |
| 8 | UI | `references/ui.md` |
| 9 | SEO and AI visibility | `references/seo.md` |
| 10 | Code quality | `references/code-quality.md` |
| 11 | Style genome | `references/style-genome.md` |
| 12 | Agent memory | `references/agent-memory.md` |
| 13 | Repository | `references/repo.md` |
| 14 | Build completeness | `references/build.md` |
| 15 | Roadmap and delivery | `references/roadmap.md` |
| 16 | Deployment | `references/deploy.md` |
| 17 | Observability | `references/observe.md` |
| 18 | Launch readiness | `references/launch.md` |

For each check, update its outcome, confidence, evidence references, and finding ids. Preserve the catalog-provided weight. A routing check with zero direct weight must map its finding to the weighted owning check it affects. In plan-aware mode, the generated AUDIT.mdx derives each finding's R-id from its mirrored check ids by A-to-R substitution and skips audit-only checks; nothing is hand-added and no R-id is stored in AUDIT.json.

When the host supports subagents, fan out one applicable domain per fresh context. Give each context only its domain module, the selected check definitions, audit metadata, and the relevant paths, signals, absences, and hashes already present in EVIDENCE.json. Do not send prior domain reasoning or the whole repository transcript. Each domain context returns a read-only check-ledger delta, evidence references, candidate findings, and escalation leads. The orchestrator alone merges ids, applies ownership, refutes candidates, and writes AUDIT.json. When subagents are unavailable, preserve the same isolation by loading one module at a time and discarding domain-local reasoning after its delta is merged.

The generated catalog labels security and build completeness `deep-capable`; all other domains are `screening`. It also carries one escalation criterion per domain. When that criterion is met, state that the catalog ceiling was reached, name the specialist assessment required, and list up to three repository-specific leads. A depth label is never a certification or a claim that specialist work occurred.

### Phase 4: Adversarial verification and clustering

For every candidate finding:

1. Re-open the exact evidence and confirm its content hash or record why the file changed.
2. Trace from entry point to sink or enforcement point.
3. Search for alternate guards, dead-code status, fixtures, generated code, framework defaults, and compensating controls.
4. Refute with a second evidence path where possible.
5. Drop, downgrade, or mark Tentative when the claim does not survive.
6. Cluster survivors by root cause and apply the ownership map.

Critical and High findings should have two independent evidence paths when the repository permits it. If they do not, confidence cannot be Certain.

Certainty costs corroboration in both directions. A Certain pass on a weighted
check also requires two independent evidence paths, because a clean bill of
health is not cheaper to assert than an alarm: it is the more dangerous error.
Two quotes from the same file are one method, not two. When a pass rests on a
single read, record it as Firm or Tentative rather than Certain.

### Phase 5: Compile scores and coverage

Read `references/exemplar.md`, including its final prose pass. Run `godaudits validate .godaudits/AUDIT.json --write`.

The compiler derives check coverage, per-domain scores, overall weighted score, verdict, finding counters, task counters, and caps. Failed checks receive deterministic severity factors. Unknown checks do not enter the quality numerator and lower coverage. Coverage below 95 prevents an audit-proof verdict; below 80 caps at needs-work territory; below 60 caps at 69. Active Critical findings, including accepted risks, cap their domain at 69 and the overall at 79. A domain below 50 caps the overall at 84.

Validation blocks on missing catalog checks, unknown ids, wrong weights, missing or unredacted evidence, credential-shaped values outside redacted evidence, broken finding-task reciprocity, unsafe parallel file overlap, task cycles, incomplete final-gate dependencies, expired risks, ownerless compliance unknowns, or stale pack versions.

### Phase 6: Remediation plan

Name the destination first. Record `audit.destination`: one or two sentences of
prose saying what reaching the end of this plan looks like. The destination
fixes the scope, so every later choice is made against it, and the final
re-audit gate's acceptance conditions are its machine-checkable form.

Convert findings into GA-numbered tasks in AUDIT.json:

- Phase 1: Stop the bleeding, every Critical.
- Phase 2: Quick wins, High or Medium with S effort.
- Phase 3: Plan now, structural M or L work.
- Phase 4: Verify first, Tentative findings whose first acceptance condition confirms the claim.
- Phase 5: Backlog, Low findings worth retaining.
- Final phase: Re-audit, dependent on every active remediation task.

Every task carries files, dependencies, reuse guidance, reciprocal finding ids, 2 to 4 acceptance conditions, one exact Verify command, and check ids. Accepted risks require finding id, named owner, acceptance date, expiry date, and review command.

When a finding's evidence lists three or more member sites, its task fixes the class, not the leaves: enforcement lands at one shared point (a central mount, a query builder, a schema constraint, a lint rule, or a CI gate) named in `reuses`, and one acceptance condition is a regression guard that fails when a new sibling site appears. A Phase 3 task that changes system shape, a module boundary, a storage shape, or an authorization model adds an acceptance condition that it write or update an in-repo ADR recording the rejected alternatives, with a Verify that greps for that record.

The plan is a map, not only a list, so record what it does not cover as
carefully as what it does. Separate the two admissions by scope, never by
sharpness. In scope and unresolved is fog: an unknown check carries the precise
`question` that would resolve it wherever the gap is describable, and a lead
this audit can see but cannot yet phrase as a check goes in `not_yet_specified`
against an applicable domain, clearing from there the moment it graduates into
a check. Ruled beyond the destination is out of scope: an excluded domain
carries its reason and a not-applicable check carries its absence evidence.
Out-of-scope work never graduates inside this audit, so it stays out of the
remediation route entirely; redrawing the scope is a fresh audit.

Run `godaudits wayfind .godaudits/AUDIT.json` to read the plan back as a route.
It reports the destination, the frontier (open tasks whose every dependency is
closed and which no session has claimed), what is blocked and by which named
task, the fog, and the out-of-scope boundary. A remediating session claims its
task before starting work so a concurrent session skips it, and re-derives the
frontier rather than trusting a rendered report older than the task state.

### Phase 7: Render and present

Run the exemplar's final prose pass over authored AUDIT.json fields, validate again, then render MDX and optional SARIF. Do not hand-edit the rendered files.

Present in chat: verdict, score and coverage, scorecard, top three risks, top three strengths, quick wins, finding and task counts, what is takeable now from the frontier, and the exact artifact paths. The artifacts are the deliverable.

### Phase 8: Evaluate the auditor when ground truth exists

When a benchmark manifest, prior human audit, or seeded fixture is available, run `godaudits evaluate`. Report recall, precision, severity accuracy, citation validity, remediation closure, clean-control rate, misses, and false positives. The repository's built-in corpus is a runtime regression gate; it is not evidence that a model audit is accurate on an unseen project.

## Modes

- **Fresh audit**: full method at a new commit.
- **Re-audit**: preserve ids and history, update check outcomes, resolve findings with evidence, add new ids only, compile both versions, and run `godaudits diff`.
- **Focused audit**: only requested domains are applicable; all others carry a scope-specific exclusion. Never present a focused score as a full-project score.
- **Medium budget**: screening checks are evaluated and deep-trace checks remain unknown in the complete ledger. This is the default.
- **Full budget**: screening and deep-trace checks are selected. Use only with explicit full-project scope and adequate context.
- **Plan-aware overlay**: conformance checks run inside every domain and carry matching R-ids.
- **Change-safety review**: separate diff-scoped state with impact leads, one or two safety facts, a five-level proof ledger, confirmed and cleared risks, and a compiled merge gate. It never contributes a repository score.
- **Static capability**: default and always available.
- **Sandbox capability**: explicit user authorization, disposable environment, no outbound network or production secrets.
- **Connected capability**: explicitly authorized read-only external evidence with connector, query, timestamp, and provenance recorded.

## What godaudits refuses

- Scores without a complete check ledger and reported coverage.
- Pass outcomes without evidence.
- Findings with invented or unreproducible citations.
- Secret values copied into artifacts or chat.
- Static predictions presented as runtime facts.
- Vague findings, duplicate root causes, or inflated severity.
- Critical or High findings without reciprocal remediation tasks.
- Hand-edited computed scores, counters, MDX, or SARIF.
- Silent module skipping or compact-prompt full audits without the domain modules.
- A blast-radius merge pass whose safety facts or before-merge reproduction stopped below executable proof.
- Executable or running-app change proof without recorded authority, environment, and isolation.
- Source mutation during the audit, unless the user separately asks for remediation after the audit is complete.

## File map

| File | Role |
|---|---|
| `SKILL.md` | Orchestrator and operating contract |
| `references/intake.md` | Mode, fingerprint interpretation, applicability, weights, ownership |
| `references/audit-format.md` | AUDIT.json, evidence, finding, task, scoring, and rendering contract |
| `references/change-safety.md` | CHANGE-REVIEW.json, impact resolvers, proof ladder, risks, clearances, and merge gate |
| `references/compliance.md` | Compliance gate and account-safety rules |
| `references/exemplar.md` | Worked quality bar |
| `guides/copy-signals.md` | Copy-signal scope, interpretation, and ownership |
| `references/<domain>.md` | 18 domain modules |
| `catalog/checks.json` | Generated 437-check machine catalog with scoring and standards metadata |
| `catalog/project-context.json` | Six forms, 37 arc-ready profiles, overlays, and artifact paths |
| `schemas/*.json` | Audit, evidence, change-review, proof-results, and benchmark schemas |
| `runtime/godaudits.js` | Self-contained zero-dependency CLI |
| `runtime/lib/` | Catalog, evidence, compiler, renderer, SARIF, diff, change-safety, wayfinding, and evaluation engine |
| `policies/` | Versioned provider-neutral and provider-specific policy packs |
| `templates/AUDIT.template.mdx` | Human-readable shape of the generated report |

## Skill version: 2.18.0