cover: Pillar 2 C coverage with enumerated misses

.github/workflows/coverage.yml

@@ -0,0 +1,42 @@
+name: coverage
+
+# Dedicated coverage workflow (new file; does not edit ci.yml).
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  c-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install lcov
+        run: sudo apt-get update && sudo apt-get install -y lcov gcc
+      - name: Measure C coverage
+        run: bash scripts/run-coverage-c.sh
+      - name: Upload coverage artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-c
+          path: |
+            docs/evidence/coverage-c-*.info
+            docs/evidence/coverage-c.log
+            docs/evidence/coverage.md
+            docs/evidence/fragments/coverage-c.json
+            docs/evidence/coverage-c-html/
+      - name: Scorecard into Step Summary
+        run: |
+          python3 tools/scorecard.py .
+          python3 - <<'PY'
+          import json, os
+          from pathlib import Path
+          card = json.loads(Path("docs/evidence/scorecard.json").read_text())
+          cov = card.get("coverage", {})
+          Path(os.environ["GITHUB_STEP_SUMMARY"]).write_text(
+              "## Coverage\n\n```json\n"
+              + json.dumps(cov, indent=2)[:6000]
+              + "\n```\n"
+          )
+          PY

.gitignore

@@ -31,8 +31,12 @@ repl
 *.gcno
 *.gcov
 coverage/
+.coverage-c/
 *.info
 htmlcov/
+docs/evidence/coverage-c-html/
+!docs/evidence/coverage-c-upstream.info
+!docs/evidence/coverage-c-expanded.info
 
 # Fuzz / bench runtime output (seed corpus is tracked)
 fuzz/logs/
@@ -57,3 +61,7 @@ Thumbs.db
 # Editor / OS
 .idea/
 .vscode/
+
+# Port kcov working reports (fragment + coverage.md stay tracked)
+docs/evidence/coverage-port-kcov*/
+docs/evidence/coverage-port.log

DECISIONS.md

@@ -268,3 +268,21 @@ Entries that only restate a diff will be deleted.
   organizer claim; future published rules can replace it with evidence.
 - Evidence: D013 and `tools/count-escape-hatches.py`; no matching published
   organizer material was found in the named searches.
+
+## D019 — Coverage: lcov on C, honest kcov bound on Zig
+
+- Constraint: Pillar 2 requires exact line/branch/function percentages for the
+  original C, every missed branch with a reason, and the same honesty for the
+  port.
+- Options: hand-roll gcov parsers; invent port percentages when kcov stays
+  silent; ship only what the tools attribute.
+- Choice: drive C with `gcc --coverage` plus `lcov --rc branch_coverage=1` and
+  `genhtml` (user-local lcov 2.0 when apt needs root). Expand the corpus until
+  only allocation-failure and defensive-default arms remain. Install kcov 43
+  and run it; when it attributes zero `src/*.zig` lines despite DWARF naming
+  those files, record `not_measured` rather than a guessed percent.
+- Consequence: C numbers are exact and reproducible; the port coverage claim is
+  an explicit tooling bound, not a silent omission.
+- Evidence: `docs/evidence/coverage.md`,
+  `docs/evidence/fragments/coverage-c.json`,
+  `docs/evidence/fragments/coverage-port.json`.

build.zig

@@ -130,7 +130,10 @@ pub fn build(b: *std.Build) void {
     cross_step.dependOn(&cross_cmd.step);
 
     _ = b.step("fuzz", "Prompt 4+: differential fuzz");
-    _ = b.step("cover", "Prompt 4+: coverage-driven corpus");
+    const cover_cmd = b.addSystemCommand(&.{ "bash", "scripts/run-coverage-c.sh" });
+    cover_cmd.setCwd(b.path("."));
+    const cover_step = b.step("cover", "lcov coverage of original C + evidence fragment");
+    cover_step.dependOn(&cover_cmd.step);
     _ = b.step("bench", "Prompt 5+: benchmarks");
     _ = b.step("enumerate", "Prompt 4+: exhaustive enumeration");
     _ = b.step("alloc-fault", "Prompt 4+: malloc failure injection");