Add comprehensive coverage documentation

[Copilot]

Creates docs/contributing/testing/coverage.md documenting code coverage practices, tooling, and expectations per issue #89.

Coverage Strategy

• Targets: 85% overall, 90% business logic, 95% utilities
• Exclusions: Binaries, E2E infrastructure, adapters requiring real infrastructure, linting package
• Philosophy: Coverage as informational tool, not blocking gate

Cargo Aliases Reference

Documents all coverage commands from .cargo/config.toml:

Alias	Purpose
cargo cov	Terminal summary
cargo cov-check	Validate ≥85% threshold
cargo cov-lcov	LCOV format (.coverage/lcov.info)
cargo cov-codecov	Codecov JSON (.coverage/codecov.json)
cargo cov-html	HTML report (target/llvm-cov/html/)

Integration Points

• Pre-commit: Final step in scripts/pre-commit.sh, non-blocking, informational only
• CI/CD: .github/workflows/coverage.yml generates artifacts on all pushes/PRs, non-blocking
• PR Reviews: Guidelines for when to request tests vs. accepting coverage gaps

Changes

• docs/contributing/testing/coverage.md - New 557-line comprehensive guide
• docs/contributing/testing/README.md - Add navigation link
• project-words.txt - Add "undertested" term

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Write coverage documentation</issue_title>
<issue_description>Parent Epic: #85
Prerequisites: #88 must be completed first (testing documentation refactoring)

Overview

Create comprehensive code coverage documentation (docs/contributing/testing/coverage.md) to provide guidance on coverage expectations, how to run coverage locally, how coverage is checked in CI/CD, and how coverage should be evaluated in PR reviews.

This is a new documentation file that will be added to the refactored testing documentation structure created in issue #88.

Goals

• Create new documentation file docs/contributing/testing/coverage.md
• Document all coverage commands and aliases
• Explain coverage expectations and thresholds
• Provide guidance for PR reviews involving coverage changes
• Document the pre-commit coverage check behavior
• Explain CI/CD coverage workflow
• Add link to coverage.md in testing README navigation

Document Structure

The new file should include these sections:

1. Overview - What coverage is and why it matters
2. Running Coverage Locally - All cargo coverage commands
3. Coverage Thresholds - Project targets (85% overall, granular targets)
4. What Gets Measured - Include/exclude rules
5. Pre-commit Integration - How coverage check runs
6. CI/CD Coverage Workflow - GitHub Actions workflow details
7. Interpreting Results - How to read coverage reports
8. PR Review Guidelines - When coverage drops are acceptable

Implementation Plan

Phase 1: Create Core Documentation (40 minutes)

• Create docs/contributing/testing/coverage.md
• Write Overview and Running Coverage Locally sections
• Document all cargo aliases from .cargo/config.toml

Phase 2: Coverage Strategy (30 minutes)

• Document coverage thresholds and targets
• Explain what code is measured and what's excluded
• Add examples of coverage output

Phase 3: Integration Documentation (20 minutes)

• Document pre-commit coverage check
• Document CI/CD workflow behavior
• Explain non-blocking nature

Phase 4: Guidance and Best Practices (30 minutes)

• Write section on interpreting coverage results
• Document PR review guidelines
• Add troubleshooting tips

Phase 5: Navigation and Cross-linking (15 minutes)

• Add link to coverage.md in docs/contributing/testing/README.md
• Add cross-references to related documentation
• Verify all links work

Phase 6: Review and Polish (15 minutes)

• Run markdown linter
• Review for clarity and completeness
• Ensure examples are accurate

Acceptance Criteria

• New file docs/contributing/testing/coverage.md created with complete documentation
• Link to coverage.md added in docs/contributing/testing/README.md navigation section
• All cargo coverage aliases documented (cov, cov-check, cov-lcov, cov-codecov, cov-html)
• Coverage targets clearly defined (85% overall, 90% business logic, 95% utilities)
• Exclusions documented (binaries, E2E infrastructure, adapters, linting tools)
• Pre-commit coverage check behavior is clearly explained
• CI/CD coverage workflow is documented
• PR review guidelines for coverage changes are clear
• All markdown passes linting
• All cross-references work correctly

Related Documentation

• Testing Conventions - Main testing documentation (after Refactor testing documentation structure #88 completes)
• Development Principles - Quality standards
• Pre-commit Process - Pre-commit workflow

Notes

• This is a new file - docs/contributing/testing/coverage.md does not exist yet
• Must be created AFTER issue Refactor testing documentation structure #88 completes (testing documentation refactoring)
• The documentation should reflect actual behavior, not aspirational features
• Emphasize the non-blocking, informational nature of coverage checks
• Make it clear that coverage is a tool, not a goal
• Provide practical examples that contributors can run immediately

Dependencies

Before This Issue: #88 - Creates the docs/contributing/testing/ directory structure
After This Issue: None - This is the final documentation task in the EPIC</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Write coverage documentation #89

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[josecelano]

ACK f895f01

[josecelano]

ACK f895f01