docs(coverage): regenerate the measured table from the command that measures it

tools/coverage.sh

@@ -6,8 +6,10 @@
 # capture src/** with lcov into build/cov/coverage.info, render the HTML report
 # under build/cov/html/, print the per-file table, and exit non-zero when
 # tools/coverage_floor.py finds a file below 80% lines or the src/ aggregate
-# below 90%. The numbers and the floors are the contract docs/coverage.md
-# states; `docs/coverage.md` also records how to re-read the table from here.
+# below 90%. The floors are tools/coverage_floor.py's constants; the measured
+# table and the floor verdict are written back into docs/coverage.md's generated
+# region by `coverage_floor.py --write-doc`, from the very report this run
+# captured, so that document cannot drift from the command that measures it.
 #
 # Idempotent by construction: gcov counters accumulate in .gcda files, so a
 # second run that inherited the first run's counters would report a superset of
@@ -31,6 +33,7 @@ readonly FLOOR="$ROOT/tools/coverage_floor.py"
 readonly RAW="$BUILD/coverage.raw.info"
 readonly INFO="$BUILD/coverage.info"
 readonly HTML="$BUILD/html"
+readonly DOC="$ROOT/docs/coverage.md"
 
 log() { printf '==> %s\n' "$*"; }
 
@@ -87,6 +90,13 @@ python3 "$FLOOR" --table "$INFO"
 readonly FLOOR_STATUS=$?
 set -e
 
+# The measured table is written into the document that states it, from the very
+# report this run captured, so docs/coverage.md cannot drift from the command
+# that produces it. This happens before the floor gate below, so a failing tree
+# still gets an honest table (and its failure recorded) in the document.
+log "regenerating the measured table in $DOC"
+python3 "$FLOOR" --write-doc "$DOC" "$INFO"
+
 if (( FLOOR_STATUS != 0 )); then
   printf '\ncoverage: FLOOR FAILED (exit %d) -- report %s, HTML %s/index.html\n' \
     "$FLOOR_STATUS" "$INFO" "$HTML" >&2