code-quality-auditor

Code Quality Auditor

Check implementation against knowledge base properties and conventions. Uses only built-in tools (grep, wc, read) — no external linters required.

Steps

1. Load KB References

• Read kb/properties.md for invariants, constraints, and quality thresholds.
• Read kb/glossary.md for canonical naming conventions and term definitions.
• Read kb/spec.md for architectural boundaries and module responsibilities.
• Read kb/architecture.md (top-level and per-module, if present) for declared structural expectations — module boundaries, dependency direction, layering. Check code structure against them; a divergence is a finding (cite file:line), and expectations that are not statically verifiable are noted as such, never assumed satisfied.

2. Check: Function Size

• Scan source files for function/method definitions.
• Measure line count per function (use grep + wc approach).
• Flag functions exceeding the threshold defined in kb/properties.md; if unspecified there, use the max-function-length limit from the project's code-quality rule (.claude/rules/code-quality.md) — do not re-declare the number here.
• Exclude test files from size checks unless properties.md says otherwise.

3. Check: DRY Violations

• Search for duplicated code blocks (identical or near-identical sequences of 5+ lines).
• Look for repeated patterns: duplicated error handling, copy-pasted validation logic, repeated configuration blocks.
• Flag each duplication with both locations.

4. Check: Naming Consistency with Glossary

• For each term in kb/glossary.md, search the codebase for variant spellings, abbreviations, or synonyms.
• Example: if glossary defines "Transaction", flag code using "tx", "txn", "trans" inconsistently.
• Check that type names, function names, and module names use glossary-canonical forms.

5. Check: Invariant Preservation

• For each invariant in kb/properties.md, verify the code maintains it:
  • If an invariant says "X is never null", search for code paths where X could be null.
  • If an invariant says "Y is always called before Z", trace call sequences.
  • If an invariant says "all inputs are validated", check for unvalidated entry points.
• This is best-effort static analysis — flag suspicious patterns, don't claim proof.
• When reading kb/properties.md, skip the contents of the fenced code-intel block (envelope: schema/kb-schema.md): those declarations are machine-checked by the roster-qa code-intel gate, and interpreting them as prose invariants would double-report.