codebase-audit

name

codebase-audit

description

Use when auditing the imp codebase for structural debt, dead code, god-objects/files, duplication, flag sprawl, or deciding whether a cleanup is worth shipping — "structure audit", "tech debt", "is this still used", "dead code", "refactor for clarity", "should we split this file", "remove this flag". Do NOT use for build/test mechanics (building-and-testing), perf/kernel work (benchmark-cuda / sm120-cuda-expert), or output quality (check-degeneration).

Codebase audit & structural debt — imp

The one hard rule

Never act on a raw finding. Verify every finding against the real code first. Fan-out audits (Explore agents, grep sweeps) systematically over-flag. On the 2026-06-09 pass, the big-ticket findings C1/C2/C4 were all REFUTED on inspection, and several "dead flags/files" were live. Treat a finding as a candidate, not a fact, until a targeted check confirms it. Most of an audit's value is in the verification, not the sweep.

Verification recipes (the load-bearing checks)

Claim	How to actually verify	Trap that fooled a past audit
"flag/symbol X is dead"	grep across src/ tests/ tools/ — tools/ IS in scope	dump_tokens/force_bos/bench.generate looked dead in src/, but are read in tools/imp-cli/main.cpp
"config field never read"	grep the leaf field for a value-read in a conditional, excluding decl/parse/copy	a local var sharing the field name hides the read (fp8_auto_legacy)
"kernel/function is dead"	trace the call graph, not just <<< sites — reachable from a live dispatch = live	q4k_imma cache was dead, but mmq_q4k_imma_tile/_reorder are LIVE via q4k_imma_prefill → mmq_q4k_imma_gemm (called on the fly). Only the ~30-LOC cache struct was dead, not the "~1200 LOC stack"
"this file is a god-file, split it"	split on conflation, not size; check if the shared part is already factored	gdn.cu/gemm.cu/sampling.cu/json_schema.cpp are each one cohesive domain. The 6 attention_paged* variants already share attention_paged_common.cuh (online-softmax loop) — only dequant differs
"rewrite this into a registry/template"	no speculative abstraction — need a concrete bug, not a smell	the weight_map.cpp if (!matched) ladder works and is readable; a mis-mapped tensor name = garbage output. Risk > cosmetic gain
"imp.conf key is inert"	is it read in src/ AND tools/? Is the live path the C-API instead?	server.prefix_cache etc. were parsed but unread — live enablement bridges at engine init (PR #636)

Workflow

1. Fan out — Explore agents / grep to surface candidates (breadth is fine here).
2. Verify each with the recipe above. Demote refuted ones immediately.
3. Write it up — docs/audit/structural_debt_YYYY_MM_DD.md. Counts are evidence, not estimates. Keep a "Refuted (do not re-chase)" section so the next pass doesn't re-flag the same false positives.
4. Ship cleanups as small PRs (REQUIRED SUB-SKILL: building-and-testing) — branch off main, never stack, Docker make build + make test-unit, prefer batching related nits. Behavior-sensitive removals: also a coherence check (check-degeneration).

File-size gate (god-file findings go through this, not ad-hoc splits)

tools/check_filesize.py (config: tools/filesize_thresholds.toml) measures code LOC (comments/blanks stripped) per category — kernel .cu warn>500/hard>600, normal TU warn>600/hard>800, header warn>500/hard>700. CI job File size: advisory warn step + blocking hard step. The real cost metric is recompile blast radius (one .cu = one ptxas TU), not line count — split on compile-time isolation (kernel def / host wrapper / explicit instantiations), never on size alone. A legitimately monolithic file goes into [allow] in the toml with a reason (empty reason is rejected). Baseline + per-file rationale: docs/audit/AUDIT_FILESIZE.md.

Priors — settled, do NOT re-flag

From the structural-debt audit chain (D1–D4 / C1–C8, archived in docs/archive/README.md; current verdicts in docs/audit/housekeeping_2026_06_13.md):

• exec/ god-object (GraphExecutor) is intrinsically forward-pass-coupled; the D2 runner-extraction track ENDED (cosmetic friend-backdoor only). Header split done (1188→584 lines). Don't re-attempt runner classes.
• ModelProfile (D1) centralized arch facts — don't reintroduce scattered cfg.arch==.
• gdn.cu is domain-cohesive ("don't touch"); the compute/ files are not god-files.
• The two-config-systems split (RuntimeConfig global vs ModelConfig::Overrides) is known and deliberate; config keys use the typed-binder B/I/F/S(...) ladder (PR #626).
• Audit #5 (2026-07-07, docs/audit/structural_debt_2026_07_07.md): server layer is the dominant debt source → issues #888–#897 filed. Before a new pass, read that report's NOT-flagged list — re-flagging its verified negatives wastes the sweep. Companion: docs/audit/vram_audit_2026_07_07.md (note: a VramOwned type does NOT exist — past audits hallucinated it).

Red flags — you are about to over-flag

• About to delete code because a sweep said "no references" → did you grep tools/?
• About to split a file because it's big → is it conflated or just one large domain?
• About to rewrite a working ladder/loader for elegance → where's the concrete bug?
• Reporting LOC of "dead" kernels → did you trace the call graph, or just <<<?