Codebase hygiene audit

What this audit answers

The codebase hygiene audit asks whether the repository is understandable and maintainable enough for a new engineer or coding agent to build, inspect, and change it without avoidable friction. It looks at broad repository smells rather than judging architecture style or demanding a rewrite.

The result describes the checked tree and the evidence available at that revision. It is not a general measure of developer skill, team velocity, or product quality.

What Guard inspects

Guard maps tracked files, directory structure, build and maintenance commands, README guidance, ignored artifacts, generated and binary files, local-path assumptions, configuration examples, formatting and lint setup, error-handling patterns, and representative code hotspots. Safe documented commands may be run when they do not require hidden services, credentials, browsers, containers, or long setup.

Findings cite small representative samples rather than dumping every match. A pattern becomes material when it affects current understanding, reproducibility, or change safety—not merely because a token such as TODO exists once.

The 19 criteria

The scorecard covers dead, commented, or unwired code; tracked binaries and build artifacts; .gitignore; build and maintenance commands; README completeness; documented global tools; history or clone weight; directory structure; committed secrets and safe environment examples; author-home path assumptions; magic values and hardcoding; naming-language consistency; backup or version-copy files; TODO/FIXME/HACK debt; formatting consistency; local DRY/KISS; long function signatures; god modules; and ignored errors.

Each row is scored 0–5. Scores of 4–5 mean the smell is absent or isolated, 2–3 mean visible but bounded friction, and 0–1 mean a systemic problem. CI or pre-commit execution can support formatting evidence, but their absence does not reduce this audit’s formatting criterion.

How the score works

Guard calculates two independent views and keeps the more cautious result. The primary table score is the 19 criterion points divided by the maximum 95 and normalized to 0–100. The severity score starts at 100 and subtracts 65 per critical finding, 25 per high, 10 per medium, and 3 per low finding, plus at most 10 points for a major limitation that hides material surfaces.

Any critical finding caps the severity score at 39. If there is no critical finding but at least one high finding, that side is capped at 69. The final score is the lower of the normalized scorecard and the severity result, clamped and rounded to 0–100.

Limitations and boundaries

This is a read-only audit. It does not run risky setup, mutate source, clean files, or turn broad architectural preference into a finding. Security, dependency, CI/CD, configuration, and dead-code audits own their deeper domains; codebase hygiene may point to them while keeping its own finding focused on repository maintainability.

History depth, unavailable toolchains, large generated areas, and undocumented services can reduce coverage. A limitation affects the score only when it hides a material surface.

Improvements and reruns

Prefer bounded improvements with an obvious verification signal: document a missing command, remove tracked build output, replace an author-specific path, restore error handling, split one genuinely mixed module, or clean a coherent cluster of stale residue. Do not combine unrelated smells into one high-blast-radius cleanup.

Rerun after the change is merged. Confirm that the original evidence is gone, commands still work, and the cleanup did not erase intentional compatibility or generated code.