Configuration hygiene audit

What this audit answers

The configuration hygiene audit asks whether a project can be configured without guesswork and whether its options form a coherent contract with the code. It evaluates the live configuration surface—not whether the team uses a fashionable schema library or has a large number of environments.

The report also derives a practical launch-readiness label: needs investigation, runnable with manual effort, ready without guesswork, or not applicable for a genuine no-configuration repository. This label summarizes scored evidence; it is not a second score.

What Guard inspects

Guard inventories configuration reads, defaults, templates, examples, schemas, manifests, environment files, option documentation, validation behavior, override layers, and representative startup paths. It compares declarations with code usage to find options that are ignored, overwritten, stale-cached, missing from templates, duplicated, or impossible for a newcomer to understand.

Secret values are redacted. A real secret belongs to the security audit, while a template design that invites people to commit secrets can still be configuration evidence.

The 11 criteria

The criteria cover the boundary between deploy-varying config and constants; justification and granularity of exposed knobs; manageable scale; safe defaults; deferred-decision residue; declared options that actually take effect; code reads that are declared; template presence and synchronization; loud validation; discoverable option context; and one authoritative source per value.

Each applicable row is scored 0–5. Some maturity signals—typed schemas, dynamic defaults, per-instance divergence, or configuration checks—can strengthen confidence, but their absence is neutral. Guard does not create a complaint merely because a team lacks optional tooling.

How the score works

Applicable criterion points are normalized to 0–100; all 11 criteria produce a maximum of 55. Confirmed findings then subtract 20 points for critical, 8 for high, 3 for medium, and 1 for low impact, with deductions capped at 35.

Evidence-backed caps apply afterward: inability to start or configure the project from templates or discoverable docs caps the score at 59; widespread no-effect options or undeclared code reads cap it at 69; a config-heavy project with neither a discoverable template nor option context is capped at 69; and a critical condition that makes correct deployment impossible or silently unsafe caps it at 39.

The final score is the minimum of the risk-adjusted result and every applicable cap. Credit-only signals and observations cannot lower it.

Limitations and boundaries

The audit is read-only and cannot prove runtime values managed entirely outside the repository. Unavailable external configuration is described as a coverage limit. Whole detached configuration surfaces belong to the dead-code audit; pipeline syntax belongs to CI/CD; package-manager and registry configuration belongs to dependency hygiene; actual secret exposure belongs to security.

Improvements and reruns

Good candidates repair one part of the contract: wire or remove a no-effect option, declare a shadow read, synchronize a template, replace an undecided mandatory value, document when to change an option, deduplicate an authority, or add loud validation. The safest change preserves existing deployment semantics unless the owner explicitly approves a behavior change.

After merge, rerun against the new commit and verify both sides of the contract: the declaration remains discoverable and the code consumes or validates it as documented.