From 65da2a3e63caa6c66c32336841d7096a2f7b76af Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 7 May 2026 23:49:41 +0000
Subject: [PATCH] docs(ci): document coverage lane

Adds docs/ci/coverage.md explaining Codecov claim boundaries and
artifacts.

Documents:
- What coverage answers (execution-surface evidence)
- What coverage does not answer (diff parser, rule eval, renderers, etc.)
- Separate proof lanes (test, conformance, golden, mutation, fuzz)
- Workflow triggers and configuration
- Durable artifacts and receipts

Codecov claim boundary: Rust execution-surface evidence only.

https://claude.ai/code/session_01VboXJ243Rjf8hJFzcdVJWE
---
 docs/ci/coverage.md | 55 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 docs/ci/coverage.md

diff --git a/docs/ci/coverage.md b/docs/ci/coverage.md
new file mode 100644
index 00000000..767dddaf
--- /dev/null
+++ b/docs/ci/coverage.md
@@ -0,0 +1,55 @@
+# Coverage
+
+Codecov coverage is Rust execution-surface evidence.
+
+## What it answers
+
+> Did tests execute this Rust surface?
+
+## What it does not answer
+
+- whether diff parsing is correct,
+- whether rule evaluation is correct,
+- whether inline suppressions are correct,
+- whether Markdown, SARIF, JUnit, Checkstyle, GitLab, CSV, TSV, or sensor rendering is complete,
+- whether LSP diagnostics and code actions are correct,
+- whether false-positive baselines or trend history are correct,
+- whether mutation adequacy is strong,
+- whether fuzzing is sufficient,
+- whether release readiness is proven.
+
+Those are separate proof lanes:
+- **Test**: unit, integration, golden, mutation, fuzz
+- **Conformance**: parser correctness, rule semantics, rendering completeness
+- **Golden**: expected input/output pairs for parser, rules, and renderers
+- **Mutation**: algorithmic adequacy under perturbation
+- **Fuzz**: robustness under random input
+
+## Execution surface
+
+The Coverage workflow runs on:
+- push to `main`,
+- `workflow_dispatch` (manual trigger),
+- PRs labeled `coverage`, `full-ci`, or `ci:full`.
+
+## Configuration
+
+Coverage is configured in `codecov.yml` with:
+- Project coverage target: auto with 5% threshold (informational only)
+- Patch coverage target: 70% with 20% threshold (informational only)
+- Codecov comments disabled
+- Codecov GitHub check annotations disabled
+
+## Artifacts
+
+Durable receipts are produced:
+- `coverage.json` — LLVM coverage report (JSON)
+- `coverage.txt` — LLVM coverage report (text)
+- `lcov.info` — LCOV coverage data
+- `target/coverage/coverage-receipt.json` — claim boundary receipt
+- GitHub Actions coverage artifact (stored for 14 days)
+- Codecov dashboard (if CODECOV_TOKEN is set)
+
+## Tool
+
+Coverage is collected by `cargo-llvm-cov`, which instruments tests with LLVM profiling and generates LCOV reports.