Nuke Audit

Nuke Audit

Preflight → audit → converge → spec → stop. This skill produces a findings ledger and a phased fix spec, then hands off — nuke-exec executes the spec in a fresh session (map: references/family-map.md). It never fixes anything itself.

Arguments

[mode] — micro | light (default) | full | unlimited | plan (print the preflight plan, then stop) [scope] — whole codebase (default) | changed (vs HEAD) | staged | branch (vs main/master) | <path or glob> [--ask] — pause at the preflight plan for confirmation. Default is no gate: the plan prints and the run starts immediately (references/preflight.md). [--yes] — skip the one gate that remains without --ask: unlimited confirms before running, because it can burn a weekly plan in one sitting.

A bare full or unlimited always means the mode, never the scope — nuke-audit full is a full audit of the whole codebase; nuke-audit light src/ is a light audit of src/.

Modes

Convergence threshold (all modes): medium+. A round is dry when it confirms zero new medium+ findings. Low/info are still recorded — U-### unverified in micro/light, skeptic-batched in full/unlimited — but NEVER reset the dry counter. The threshold controls convergence only, not what auditors report. Do not tell auditors to report "medium+ only", skip low/info, or omit low/info from the ledger just because the dry counter ignores them. rounds.md names the active threshold every round.

Mandates

These override convenience at every step:

1. Respect the mode and the tier table. In micro/light never spawn one agent per lens or per finding; in full never exceed the 20-auditor wave cap — grow each lens's territory instead; in unlimited never shrink a wave to save tokens. Skeptics are locality-batched in every mode, unlimited included — the skeptic wave is sized by the batch plan in references/skeptic-protocol.md, never by candidate count. Assign each role the tier references/model-tiers.md gives it — never silently upgrade a role's tier.
2. Main context stays thin. The orchestrator never pulls source files into the main context. Agents receive file paths and artifact paths, not contents; agents return short structured results; everything durable lives in the artifact files.
3. Read-only on the codebase. Writes happen only under .nuke/ — the run directory plus the shared .nuke/repo-map.md and .nuke/calibration.log. Never run git add, git commit, or git stash; never edit source, config, or .gitignore. Leave .nuke/ untracked.
4. Fresh run directory. Never write into an existing audit run. Preflight allocates a new run_dir when the plan is applied; if the computed path already exists, append -2, -3, … until mkdir succeeds. Every artifact of this audit lives only there; pass that exact path in every agent prompt.
5. Evidence before existence. A candidate missing any field of the schema in Phase 2 does not enter the ledger. A convergence claim without the rounds log backing it is false reporting.
6. Low/info accounting is mandatory. Every auditor prompt must ask for schema-complete candidates of all severities. Low/info entries are cheap ledger work, not convergence blockers; record them as confirmed/rejected/unverified according to mode. If a subagent mentions a low/info observation without the full schema, either ask for the missing fields or record in rounds.md that the observation was invalid, not silently dropped.

Artifacts

run_dir = .nuke/<YYYY-MM-DD>-<HHmmss>-<slug>/ — local 24-hour clock, e.g. .nuke/2026-07-02-131502-src-engine/.

Pipeline

Phase 0 preflight (plan → apply → run_dir)
  ─→ Phase 1 recon ∥ quality-bar research
  ─→ Phase 2 convergence loop:  wave → skeptics → ledger ─┐
                                └─ until dry target met ──┘
  ─→ Phase 3 scorecard + fix spec ─→ Phase 4 handoff (STOP)

Phase 0 — Preflight

Read references/preflight.md and follow it exactly:

1. Resolve arguments into a concrete scope: file list + file count + KLOC.
2. Build the file-type → skill map from the local skill library, listing it once (rules in references/stack-adapters.md).
3. Compose the round-1 wave and tier assignments (references/model-tiers.md, audit table).
4. Estimate the cost band from preflight.md's calibration table.
5. Print the plan block and apply it — the run starts immediately by default. The gate engages only for --ask or unlimited mode (--yes skips it); plan argument → print and STOP, no run_dir. A resolution step that cannot complete (broken gate command, missing installs) follows the unblock protocol in references/preflight.md — classify, fix environmental blockers (max 2 attempts, recorded as unblocked: in plan.md), continue; never stall the run on tooling.
6. Create the fresh run_dir, write plan.md into it.

Phase 1 — Recon ∥ quality-bar research

Run both in parallel; both distill into context.md.

Recon — one scout produces:

1. Project instruction files (CLAUDE.md, AGENTS.md, .cursorrules, .github/copilot-instructions.md) → the conventions agents must respect. These define what is intentional, not a finding.
2. Stack and manifests; the per-path-prefix gates table (test/typecheck/lint per prefix — protocol in references/stack-adapters.md); gateless areas flagged per the same file. The gates table goes verbatim into the fix spec later.
3. The final scope file list (exclude vendored, generated, lockfiles). Area split: confirm the split recorded in plan.md; a changed split is a plan change. light: scope past ~80 files or ~40 KLOC → split into 2 areas by directory/feature. full: no chunking — every lens auditor hunts the whole scope; past ~200 files or ~80 KLOC, give correctness, structure, simplicity, and types one agent per half-scope (split by directory), still within the 20-auditor cap. unlimited: chunk files into areas of 5–15 by directory/feature (15–25 for very large scopes — grow chunk size before ever dropping a lens).
4. The file-type → skill map from preflight, recorded for every agent.
5. Write or refresh .nuke/repo-map.md (stamped with date + HEAD) from context.md's durable parts — stack, conventions, gates, architecture — never run-specific scope. Other nuke skills consume it as recon cache.

Quality-bar research — one session-tier researcher (or the orchestrator where search tools are main-context-only); degrade gracefully; skip unavailable tools:

1. Web-search current best practices for the detected stack, current year in queries — deprecations, new idioms, changed defaults.
2. Docs lookup (context7 or equivalent) for the major libraries in use.
3. Note which amplifier skills from the lens catalog exist locally. Where no amplifier exists, the lens text plus this quality bar IS the charter — deepen the research for those lenses proportionally.

The distilled "Quality bar" section of context.md defines what the quality bar means for this repo today.

Phase 2 — Convergence loop

Read references/lens-catalog.md, references/skeptic-protocol.md, and references/ledger-format.md before composing the first wave.

dry = 0; round = 1; threshold = medium+; ledger = empty findings.md
repeat:
  1. compose wave per mode (below). Round 1: agents get context.md + charter.
     Rounds 2+: auditors get the ledger DIGEST only; skeptics get full entries for
     their assigned candidates + the digest (rule in references/ledger-format.md)
  2. auditors report candidates of every severity not already in the ledger — full schema below required
  3. skeptic pass per references/skeptic-protocol.md — the orchestrator groups
     candidates into batches of ≤20 / ≤8 files, logs the batch plan in rounds.md
     BEFORE spawning any skeptic, then spawns ceil(N / 20); micro/light:
     low/info candidates get NO skeptic and enter the ledger as U-### unverified
  4. confirmed → F-### at the skeptic's severity (recalibrations bind — for the ledger
     AND the dry counter) · rejected → R-### · unverified low/info → U-###
  5. log the round in rounds.md, threshold named
  6. dry = (new medium+ confirmed == 0) ? dry + 1 : 0    # low/info never reset dry
  7. apply mode rules: charter retirement (micro) · half-wave (light) · delta scope
until dry == target (micro 1; others 2) or round > cap (micro 4; light/full 8; unlimited 10)

Candidate schema — every field mandatory; a candidate missing any is invalid and must not be reported:

1. lens + severity + one-sentence severity justification
2. file:line references for every involved site
3. at least one verbatim quoted line per cited site
4. numbered end-to-end trace proving the claim
5. proposed fix, imperative, one–three sentences
6. refutation attempt — the strongest reason this is NOT real; the author who cannot refute it reports it; the author the refutation convinces discards it

Low/info reporting rule: never convert "threshold: medium+" into "report medium+ only." Low/info candidates that satisfy the schema enter the ledger in the same merge pass as medium+ candidates. If the user changes the dry target, round cap, or convergence rule mid-run, keep this reporting rule unless they explicitly opt out of low/info recording; if they do opt out, state the limitation in plan.md, rounds.md, report.md, and fix-spec.md counts so the final low/info numbers are not presented as exhaustive.

Delta scope (rounds 2+, micro/light/full): hot charters or lenses re-run over the delta only — files cited in the previous round's new findings plus files importing or imported by them — never the whole scope again. Fresh-eyes and miss-hunter agents are never delta-scoped.

Charter retirement (micro): a charter that confirms zero new medium+ in a round is retired for the rest of the run.

Half-wave (light): a round confirming <3 new medium+ with rejection rate <10% → halve the next wave's auditor count (round up).

If the round cap is hit without convergence, report honestly: "NOT converged", with the per-round trail. Never fake convergence. In light/full/unlimited a dry round 1 still needs a dry round 2.

Wave composition

micro — round 1: 4 charter auditors (behavioral, security, structural, quality — lens bundles in references/lens-catalog.md), each hunting the whole scope. Rounds 2+: hot charters only (confirmed a new medium+ last round), delta-scoped. Skeptics per the batch rule — at micro scale usually one — every candidate verdicted separately.

light — round 1: one auditor per charter; if recon split the scope into 2 areas, behavioral and quality get one agent per area (6 agents), security and structural stay whole-scope; hard cap 8. Rounds 2+: one delta-scoped agent per hot charter, plus 1 fresh-eyes generalist (full lens catalog, no area) on rounds 2, 4, 6 only, plus 1 miss-hunter in round 2 — charter: "what could previous waves structurally not have seen?" (cross-file interactions, runtime config, generated code, scripts, docs drift). After round 2 the miss-hunter returns only in the round following a new medium+ confirmation.

full — round 1: one auditor per lens from references/lens-catalog.md (15, plus ai when an ai surface is detected), each hunting the WHOLE scope through its single lens — per-lens depth without the chunk explosion. Never one agent per (lens × chunk) in this mode: the wave is sized by the lens count, hard cap 20 (very large scopes split per the recon rule, inside the cap). Rounds 2+: hot lenses (confirmed a new medium+ last round) delta-scoped + 2 fresh-eyes generalists + 1 miss-hunter in round 2 (later only in the round following a new medium+ confirmation).

unlimited — round 1: one agent per (per-chunk lens × chunk) + one whole-scope agent per cross-cutting lens; security additionally gets one agent per entry surface (surface detection in references/stack-adapters.md). Rounds 2+: rotate the chunk axis (by-directory ↔ by-feature ↔ by-layer), re-run every lens that confirmed findings last round on its hot areas, add ≥3 fresh-eyes generalists and 1 miss-hunter. Never shrink a wave, drop a lens, or merge charters. The plan block must state the computed agent count — this is the mode that once dispatched 300+ slices in one round, which is exactly why it gates on confirmation and why nothing else may compose waves this way.

Phase 3 — Scorecard & fix spec

Read references/fix-spec-template.md first.

1. Scorecard (into report.md): score each lens 1–5 (5 = no issues; 1 = critical/pervasive). Target after fixes is 5/5 everywhere; any lens that cannot reach 5/5 gets a stated reason and the maximum achievable.
2. Spec writing: dispatch one spec-architect + one completeness reviewer (tiers per references/model-tiers.md). The architect writes fix-spec.md from the ledger; the reviewer verifies: every confirmed F-### maps to ≥1 task; every U-### is routed to the phase touching its files; every task lists files + exact change + a mechanically checkable Accept (grep, test run, or quoted line); batches within a phase touch disjoint files; phases are dependency-ordered; the per-prefix gates table and the file-type → skill map are present. Reviewer rejects → architect revises → loop (micro/light/full: cap 3 cycles; unlimited: until it passes).
3. Phase ordering: structural moves/renames → DRY extractions and architecture changes → local fixes (slop, types, errors, simplicity, dead code) → tests → docs/cleanup.
4. The spec covers all findings — every severity, U-### included. Record mode and tier assignments in the spec header; nuke-exec defaults to them.

Phase 4 — Handoff (STOP)

Report to the user and stop — do not start fixing:

• Mode, rounds run, dry trail with threshold (e.g. light · 4 rounds: 12 → 3 → 0 → 0 (medium+))
• Counts: confirmed by severity, rejected, unverified + the scorecard
• Artifact paths. Append the run's calibration line to .nuke/calibration.log (format in references/preflight.md)
• The handoff line: "Run the nuke-exec skill on .nuke/<run>/fix-spec.md in a fresh session — or hand fix-spec.md to any AI agent; its Executor context + Execution protocol sections make it self-contained."

Orchestration notes

• Tiers: every spawned agent gets its role's tier from references/model-tiers.md (audit table). Platforms without per-agent model overrides → every role inherits the session model.
• All orchestrators: the run_dir exists before any agent launches (applying the preflight plan creates it); pass that exact path in every prompt. Never ask agents to infer "the latest" run directory or reuse one by date/scope.
• Claude Code: prefer the Workflow tool — the loop maps 1:1 to loop-until-dry; use schema-validated outputs for candidates and verdicts — or parallel Agent calls with run_in_background per wave. Pass model/effort per the tier mapping in model-tiers.md.
• Codex / OpenCode / Cursor / other CLIs: subagents per charter. If parallelism is unavailable, run charters sequentially — each in a FRESH context (never reuse one long context across charters; fresh eyes are the point), same ledger protocol.
• Amplifier skills: each agent loads its charter's matched skills from the file-type → skill map when they exist locally; when absent, the charter text plus the quality bar carries the lens.
• micro/light/full: wave caps are hard ceilings — grow the per-agent area, add a round, or split into two scoped runs; never exceed the cap. unlimited: concurrency limits just queue agents — never a reason to drop lenses or merge charters.