auditing-config-and-build-hygiene

auditing-config-and-build-hygiene

Are config and CI trustworthy? Secrets, env parity, reproducible pinned builds, cache correctness.

When to use

Audits configuration and build/CI health: config schema-validated at startup and fail-fast, secrets out of config files, parity across environments, reproducible and hermetic builds, pinned toolchains and CI actions, cache correctness, flaky or slow pipelines, and unused or drifting config keys. A repo-wide / scheduled audit. Use when auditing CI pipelines, Dockerfiles, build scripts, env vars, or config files.

Shape: repo. Run against the whole repository (scheduled or on demand), not a single diff.

Reviewer discipline

Report only real problems. If the code correctly handles the case, reply "No findings" and stop — do not invent issues. This guards against false positives on correct code; still report every genuine issue you do find, with its full detail.

Defects are the default; improvements are opt-in. By default this lens is defect-only: do not suggest changes to code that is already correct. When the team has opted up into improvement suggestions, a finding on already-correct code is admissible only as nit-severity, route: implementer (the author applies, defers, or ignores), and must clear the non-configurable anti-churn floor: it must genuinely improve — never offer a merely equivalent alternative — and must converge (once a dimension is as good as you can confidently make it, stop; never oscillate A→B then B→A, never re-order to an equivalent state). Defects keep the strict bar above regardless of this setting.

Top checks

The head of the full checklist — enough for a first pass without opening any reference file:

• Portability: any hardcoded paths, OS/arch assumptions, locale/encoding/timezone assumptions, or non-portable shell?
• Does CI run the full gate on the diff — lint, format-check, type-check, tests, dep/security scan — and is passing required to merge?
• Beyond that required floor, are the deterministic quality signals this stack benefits from actually present — coverage reporting (with a branch/diff threshold, not a vanity global %), a performance benchmark on the hot paths, and complexity/maintainability scoring? Their absence is a preference-tunable advisory (route: implementer), not a floor-tier block: surface "no coverage gate / no perf benchmark / no complexity budget" as a gap worth wiring up, and let a repo that deliberately skips it suppress the note (cross #17, #21).
• Is the build reproducible/hermetic enough to not depend on machine-local state (pinned toolchain, lockfiles, no network in build)?
• Is CI fast and reliable? A new slow/flaky job is a defect — parallelized, cached, deterministic?
• Is config separated from code and injected via env — no secrets or env-specific values hardcoded/committed?
• Is config validated at startup (fail fast, clear message), not lazily at first use?
• Are safe, secure defaults used (deny-by-default, TLS on, debug off in prod — cross #14)?
• Dev/prod parity: does the change keep environments close (same backing services, same config shape), avoiding env-specific code branches?

Mechanizing these checks

Where a finding here is one a tool can catch deterministically, surface that as an advisory route: implementer note next to the finding: the hand review caught it this time, and wiring the matching tool from reference/tool-rules.md into CI gates it going forward. This is a suggestion to mechanize, not a defect — it never blocks a verdict, and it falls away on a repo that already runs the tool.

Going deeper

• reference/heuristics.md — the full checklist; open it when the change sits squarely in this lens's domain.
• examples.md — concrete good/bad findings, and the output format to match.
• reference/tool-rules.md — static-analysis rules covering the mechanical subset; for wiring up linters, not needed for the judgment review itself.
• reference/sources.md — the research behind each check; for provenance, not needed during a review.