--- name: html-report-ground-truth-audit description: "Audit a self-generated HTML report: ground every numeric/code/diagram claim against the repo, fix, and prove structure + render" --- Use after generating a large HTML report (e.g. via `repo-change-html-report`) whose claims were partly reconstructed from session memory. Fabricated numbers, invented code blocks, and silently-swallowed sections are the failure modes; the audit makes each traceable to the repo, a live command, or a recorded run. ## Procedure ### 1. Enumerate every checkable claim Grep the report for numerics, file paths, symbol names, and code blocks: - line counts (`wc -l` the real file) - test counts (`grep -c '@test' tests/.bats` — NOT suite-run totals: conditional skips make raw counts differ; run-observed totals are legitimate run history, keep them labeled as such) - diff stats (`git diff --shortstat main..HEAD` — the footer's files/insertions/deletions) - commit hashes (`git log --oneline`) - "verbatim" code blocks (see 3) - diagram node lists and captions (see 4) ### 2. Ground numeric claims with one command each Fix every mismatch in place. Record the was/now pair — the audit table IS the evidence. ### 3. Verbatim code blocks: prove them For a block labeled verbatim, the exact string must exist: - live code: `grep -n '' ` - historical: `git show -- | grep -E '^[+-].*(|)'` If the block was fabricated (plausible-looking pseudo-code), replace it with the real excerpt. If condensed, the block header must say "condensed" and every shown line must be real. ### 4. Diagram claims: run the engine Behavioral diagrams (plan traces, closure graphs) must be re-derived by running the actual CLI: `python3 scripts/service-map.py plan --host ` — then edit node labels, captions, and the prose count ("four services") to match output. Cross-check derived-set diagrams against the source relation (e.g. `grep -rl 'Network=gluetun.container' */**/*.container` for who rides a tunnel). ### 5. Check for swallowed sections Large prior-session PUT ranges silently overwrite neighbors. Grep for headings/captions the plan promised; re-insert any that vanished, anchored on a fresh `read` of the region. ### 6. Structural balance Python tag-balance pass over the file: - per-tag open/close counts (`div`, `pre`, `figure`, `svg`, `table`, `span`, `figcaption`) - running-div-depth scan printing per-section balance to localize stray closers Common defect: `.ln`/`.nt` pair emitted without its `.cg` wrapper → stray ``; fix by opening `
` before the pair. ### 7. Render proof `file://` is blocked on the shared browser — serve the dir: `bash` service `python3 -m http.server --bind 127.0.0.1 --directory `, ready on that port. Then: - `browser.open({name, url: 'http://127.0.0.1:/'})` - DOM assertions via `tab.evaluate(() => …)` — NOT `tab.run` (that runs in Bun; no `document`). Sections are `

` + siblings: scope queries to `document.body`/`document.querySelectorAll`, not `#ch5 …`. - screenshot the repaired regions (scroll via `tab.evaluate(el.scrollIntoView())`), then `tab.close()` and kill the server proc (`write proc:///kill`). ## Deliver A was/now table of every fix with its ground command, plus the list of claims verified intact. State honestly which numbers are run-history and not recomputable.