ci(coverage): fail a PR when this repo's own parse-coverage report goes bad (#963)

.github/workflows/pr.yml

@@ -59,7 +59,7 @@ jobs:
           # The paginated files endpoint remains filename-only for this gate.
           FILES=$(gh api --paginate "repos/$REPO/pulls/$PR/files?per_page=100" --jq '.[].filename')
           printf '%s\n' "$FILES"
-          if printf '%s\n' "$FILES" | grep -qE '^(src/|internal/|install\.(sh|ps1)|scripts/build\.sh|scripts/smoke-test\.sh|scripts/smoke-local\.sh|scripts/smoke-fixture-server\.py|scripts/gen-third-party-notices\.sh|scripts/env\.sh|test-infrastructure/vm/(vm-smoke\.sh|windows-user-path-guard\.ps1)|Makefile\.cbm)'; then
+          if printf '%s\n' "$FILES" | grep -qE '^(src/|internal/|install\.(sh|ps1)|scripts/build\.sh|scripts/smoke-test\.sh|scripts/smoke-local\.sh|scripts/smoke-fixture-server\.py|scripts/gen-third-party-notices\.sh|scripts/env\.sh|scripts/ci/(self-index-coverage-gate\.sh|coverage-gate-allowlist\.txt|parse-partial-baseline\.txt)|tests/test_coverage_gate_contract\.sh|test-infrastructure/vm/(vm-smoke\.sh|windows-user-path-guard\.ps1)|Makefile\.cbm)'; then
             echo "product=true" >> "$GITHUB_OUTPUT"
           else
             echo "product=false" >> "$GITHUB_OUTPUT"
@@ -127,6 +127,21 @@ jobs:
           CCACHE_DIR: ${{ github.workspace }}/.ccache
           CCACHE_MAXSIZE: 1000M
 
+      # Index this repo with the binary just built and check its own
+      # parse-coverage report is still useful advice (#963). Ubuntu only: the
+      # flagged line ranges depend on which conditional-compilation branches
+      # the preprocessor keeps, so they differ per platform. The gate asserts
+      # proportions, never exact line numbers.
+      - name: Parse-coverage gate (Ubuntu)
+        if: matrix.os == 'ubuntu-latest'
+        env:
+          # The gate compares this branch against the merge base, so it needs
+          # the commit GitHub used to build the merge. Without this it falls
+          # back to the first parent of HEAD, which is the same commit on a
+          # pull_request checkout — this makes it explicit rather than lucky.
+          COVERAGE_GATE_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: scripts/ci/self-index-coverage-gate.sh "$(pwd)/build/c/codebase-memory-mcp"
+
       - name: Build prod + smoke (macOS)
         if: matrix.os == 'macos-14'
         run: |

Makefile.cbm

@@ -98,9 +98,10 @@ endif
 KOTLIN_DEDUP_TEST_DEFINE = -DCBM_KOTLIN_DEDUP_TEST_API=1
 CALL_REFERENCE_LOOKUP_TEST_DEFINE = -DCBM_CALL_REFERENCE_LOOKUP_TEST_API=1
 INCREMENTAL_TEST_DEFINE = -DCBM_INCREMENTAL_TEST_API=1
+COVERAGE_MARKER_TEST_DEFINE = -DCBM_COVERAGE_MARKER_TEST_API=1
 CFLAGS_TEST = $(CFLAGS_COMMON) $(EDITOR_TEST_DEFINES) $(SANITIZED_DEFINE) \
 	$(KOTLIN_DEDUP_TEST_DEFINE) $(CALL_REFERENCE_LOOKUP_TEST_DEFINE) \
-	$(INCREMENTAL_TEST_DEFINE) -g -O1 $(SANITIZE)
+	$(INCREMENTAL_TEST_DEFINE) $(COVERAGE_MARKER_TEST_DEFINE) -g -O1 $(SANITIZE)
 CXXFLAGS_TEST = $(CXXFLAGS_COMMON) $(SANITIZED_DEFINE) -g -O1 $(SANITIZE) $(CXX_STDLIB_FLAGS)
 
 # TSan (can't combine with ASan)
@@ -118,6 +119,7 @@ TSAN_SANITIZE = -fsanitize=thread -fno-omit-frame-pointer
 # macro of ours.
 CFLAGS_TSAN = $(CFLAGS_COMMON) $(EDITOR_TEST_DEFINES) $(KOTLIN_DEDUP_TEST_DEFINE) \
 	$(CALL_REFERENCE_LOOKUP_TEST_DEFINE) $(INCREMENTAL_TEST_DEFINE) \
+	$(COVERAGE_MARKER_TEST_DEFINE) \
 	-DCBM_SANITIZED_BUILD=1 -g -O1 $(TSAN_SANITIZE)
 CXXFLAGS_TSAN = $(CXXFLAGS_COMMON) -DCBM_SANITIZED_BUILD=1 -g -O1 \
                 $(TSAN_SANITIZE)

internal/cbm/cbm.h

@@ -511,6 +511,21 @@ typedef struct CBMFileResult {
      * completeness guarantee. Callers should treat a flagged file as "prefer
      * grep here", never treat an unflagged file as provably complete. */
     bool parse_incomplete;
+    /* True when the ranges cover so much of the file that they are no longer
+     * useful advice — one range over 80% of the line count. The file WAS
+     * indexed, but pointing a reader at almost every line tells them nothing,
+     * so the report says "read the source" instead of listing the range.
+     *
+     * Its main customers are non-C languages. The refinement that narrows a
+     * whole-file range using the preprocessed parse only runs for C, C++ and
+     * CUDA, so a Python, Java or Ruby file whose root node is ERROR still
+     * reports 1-N.
+     *
+     * Note the naming: this field and the phase string it produces are both
+     * `parse_unusable`. The older `parse_incomplete` field emits the phase
+     * `parse_partial` instead. That mismatch is historical, not deliberate —
+     * do not copy it. */
+    bool parse_unusable;
     const char *error_ranges;
     int error_region_count;
     bool is_test_file;

scripts/ci/README.md

@@ -13,6 +13,7 @@ CI and the local infrastructure — both of which the venue-parity contract
 | `preflight-docker.sh` | Same idea for Colima/docker: prune runner-unlike residue, assert free space on the filesystem backing the docker data root (not the VM's `/`). Build cache + named volumes KEPT (the local analogue of actions/cache); `--deep` drops them. | `test-infrastructure/run.sh` |
 | `check-glibc-compat.sh` | Run a linux binary in debian:bullseye (glibc 2.31) — the portable binary must start on old glibc. | `_smoke.yml` portable legs |
 | `generate-sbom.py` | The release SPDX SBOM (vendored versions reviewable here, diffable by vendoring PRs — was inline YAML). | `release.yml` |
+| `self-index-coverage-gate.sh` | Index the merge base and this branch with the binary just built, and fail the PR only for a finding the branch ADDED (#963): a whole-file parse failure, a range list clipped without saying so, a single range over 25% of a file of 200+ lines, or a flagged-file count above the merge base's. Comparing against the base rather than a fixed number stops main moving the baseline and turning unrelated PRs red (#1972). Reads two data files: `coverage-gate-allowlist.txt` (paths it skips, each with a written reason) and `parse-partial-baseline.txt` (a record it prints, never a gate). Both trees are indexed with the SAME binary, so it cannot see an extractor change that moves both sides together. Ubuntu leg only — the flagged lines depend on which conditional-compilation branches the preprocessor keeps. | `pr.yml pr-smoke` |
 | `require-all-green.sh` | The aggregate gate: fail unless every needed job succeeded or legitimately skipped (was inline YAML). | `pr.yml ci-ok` |
 | `verify-shard-union.sh` | Prove sharded test legs lost nothing: shard count agreement, indices 1..n, identical suite lists, union of slices == full list (was inline YAML). | `_test.yml` shard-completeness |
 | `prepare-release-candidates.sh` | Copy one linker output into stripped/unstripped candidates, finalize signatures, composition-check them without execution, and record their hashes. | `_build.yml`, local artifact smoke |

scripts/ci/coverage-gate-allowlist.txt

@@ -0,0 +1,19 @@
+# Files the self-index coverage gate skips, one repo-relative path per line.
+#
+# Adding a line here is a deliberate decision, not a convenience. It says:
+# "we know this file reports a wide parse-coverage range, we have looked at
+# why, and we accept it." Write the reason above the path. A line with no
+# reason should be removed rather than trusted.
+#
+# Blank lines and lines starting with # are ignored.
+
+# One range covers lines 245-326 of a 326-line file (25.2%). The tree-sitter
+# PowerShell grammar cannot parse the `} else {` branch that runs to the end
+# of the file, so those 82 lines really are absent from the graph. This is a
+# genuine grammar gap, not a reporting error. Every other file of 200+ lines
+# in this repo sits at 3.9% or below.
+#
+# The range read 113-113,113-113,245-327 until the duplicate and the past-EOF
+# end line were fixed in cbm_error_regions_push. Narrowing it by one line did
+# NOT clear the gate: 25.2% is still over the 25% limit, so this entry stays.
+scripts/setup-windows.ps1

scripts/ci/parse-partial-baseline.txt

@@ -0,0 +1,22 @@
+# A written record of parse_partial_count when this repo indexes itself.
+#
+# NOTHING FAILS ON THIS NUMBER. The gate reports it and moves on.
+#
+# It used to be a ceiling. main could move the count on its own and every open
+# pull request then went red for a reason none of them caused — that is #1972,
+# where main gained src/daemon/runtime.c and the count went 58 -> 59 with no
+# branch involved. The gate now indexes the merge base and compares against
+# that, so the number below does not gate anything.
+#
+# What it is still for: a reader can see how far the count has drifted since
+# anyone last looked, which is the one thing a merge-base comparison cannot
+# show. Update it when you have measured a new number and can say why it moved.
+#
+# It complements the FLOOR asserted in tests/test_index_resilience.c, which
+# stops the coverage signal being switched off by accident. That one IS
+# enforced.
+#
+# 58 -> 59 on 2026-08-31. main gained src/daemon/runtime.c, whose line 47 the
+# tree-sitter C grammar cannot parse. The rise came from main, not from a
+# branch. See the commit for the measurement.
+59