kcov-debuglisted

# kcov / Coverage Debugging Playbook Actionable consolidation of ClaudeSec's hard-won coverage knowledge (PRs #116–#193). Use this when a coverage job fails, hangs, or you need to move a floor. Source of truth is always the live `.github/workflows/lint.yml`; the numbers below were current as of PR #193 (2026-06) — re-read the workflow before quoting a threshold. ## Two independent coverage gates | Gate | Job | Tool | Floor | Path | |------|-----|------|-------|------| | Python | `scanner-unit-tests` | pytest + coverage | **99%** (`scanner/lib`) | `test-reports/coverage.xml` | | Bash | `scanner-shell-coverage` | kcov v42 | **90%** | `kcov-out/merged/` (JSON located via `find`, path unstable — see §2) | These are separate. A red "coverage" check is one or the other — read the job name first. ## Decision tree ```text Coverage job is failing/slow? ├── Job HANGS or times out (>30s per test, minutes total) │ → MISSING OFFLINE GUARD. See §1. Most common kcov failure. ├── "No coverage.json found under kcov-out/" │ → MERGE-PATH DISCOVERY. See §2. ├── Reports 0% or wildly low bash coverage │ → KCOV INSTRUMENTATION (wrong target / include-pattern). See §3. ├── "Bash coverage N% is below required threshold 90%" │ → REAL REGRESSION or floor too high. See §4. └── Python pytest gate below 99% → scanner/lib SUT coverage. See §5. ``` ## §1 — Job hangs / per-test timeout (the #190 root cause) **Symptom**: `scanner-shell-coverage` (or any test calling `generate_htm