live: heartbeat sync 2026-10-18T16:47:59-07:00 (Refs #11)

agent/managed-skills/html-report-ground-truth-audit/SKILL.md

@@ -0,0 +1,48 @@
+---
+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/<f>.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 '<distinctive line>' <file>`
+- historical: `git show <sha> -- <file> | grep -E '^[+-].*(<token1>|<token2>)'`
+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 <h> <path>` — 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 `</div>`; fix by opening `<div class="cg">` before the pair.
+
+### 7. Render proof
+`file://` is blocked on the shared browser — serve the dir: `bash` service `python3 -m http.server <port> --bind 127.0.0.1 --directory <dir>`, ready on that port. Then:
+- `browser.open({name, url: 'http://127.0.0.1:<port>/<file>'})`
+- DOM assertions via `tab.evaluate(() => …)` — NOT `tab.run` (that runs in Bun; no `document`). Sections are `<h2 id>` + 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://<name>/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.