coverage

name	coverage
description	Coverage policy - 90% requirement and exclusion rules

Coverage Policy

The Requirement

90% coverage of Lines, Functions, and Branches for the ENTIRE codebase.

• 90% of ALL code, not just new code
• A single uncovered line or branch in ANY file blocks ALL commits
• Fix ALL gaps before committing

Decision Framework

When you encounter uncovered code:

Can this code path execute in production?
├─ No → ACCEPT exclusion (assert/PANIC only)
└─ Yes
   └─ What triggers it?
      ├─ User input / External data → MUST TEST
      ├─ Environment / IO failure → WRAP AND MOCK (see mocking skill)
      ├─ Vendor library error → WRAP AND MOCK
      ├─ OOM condition → REFACTOR to PANIC (see testability skill)
      ├─ Function can never fail → REFACTOR res_t to void
      └─ Broken invariant → REFACTOR to PANIC

Exclusion Policy

Allowed (LCOV_EXCL_BR_LINE only)

1. assert() - Compiled out in release builds
2. PANIC() - Invariant violations that terminate

Must be single-line. Multi-line blocks require refactoring.

Never Exclude

• Defensive programming checks (test them)
• Library error returns (wrap and mock)
• System call failures (wrap and mock)
• "Should never happen" branches (PANIC if truly impossible)
• Any code reachable at runtime

If it can execute in production, it must be tested.

Critical Rules

1. Never use exclusions without explicit user permission
2. Never change LCOV_EXCL_COVERAGE in Makefile without permission
3. Never generate HTML coverage reports (slow, unnecessary)

Incremental Progress

While 90% is the goal, progress toward 90% is valid work:

• Easy wins first
• Commit incrementally
• Respect context limits

Verification

make check-coverage

All three metrics must show 90%.

Related Skills

• lcov - Finding gaps, reading coverage files, marker syntax
• testability - Refactoring patterns for hard-to-test code
• mocking - Testing external dependencies