binder/tools/audit — Editorial and Registry Audits
Detection tooling that scans textbook content against the house style rules and the MLSys·im registry, plus the verification scripts that back the book checks.
Fmt / notation audit (inline {python} numbers, spurious .0): see
fmt/README.md.
Registry migration build (constants → zoos)
End-to-end gate for the completed mlsysim registry migration:
python3 binder/tools/audit/check_registry_migration_build.py
Individual tools:
| Script | Purpose |
|---|---|
book_check_registry_sources.py |
Ban legacy flat constants / alias paths in QMD LEGO cells |
generate_appendix_constants.py --verify |
Execute appendix assumption-table cells against live registries |
refresh_mlsysim_constants_yamls.py --finalize |
Mark audit YAML inventory should_change: false |
audit_mlsysim_drift.py |
Detect hand-coded canonical constant drift |
Style scan
binder/tools/audit/
├── README.md — this file
├── __init__.py
├── protected_contexts.py — LineWalker + inline span detection
├── ledger.py — Issue + Ledger JSON model
├── scan.py — scanner CLI
├── accept_list.py — persistent false-positive accept-list
├── accepted_fps.json — accepted false positives
├── verify.py — structural verification checks
├── math_render/ — rendered HTML/PDF math-leak audits (see math_render/README.md)
└── checks/
├── __init__.py
├── vs_period.py — bare 'vs' → 'vs.'
├── compound_prefix.py — pre-/non- close-up (strict 6-term list)
├── percent_symbol.py — '%' → 'percent' in body prose
├── lowercase_prose_references.py — 'Chapter 12' → 'chapter 12'
├── acknowledgements_spelling.py — British → American
├── binary_units.py — GiB/TiB in prose (detection only)
└── h3_titlecase.py — H3+ headings in title case (detection only)
The scanner is read-only. It reports issues; an editor decides each fix in context.
Persistent accept-list
accept_list.py + accepted_fps.json together record editorial verdicts on
scanner false positives (proper-noun-heavy headings, named principles,
legislation, after-colon CMS 8.158 caps, D·A·M/C³ taxonomy axes). After every
scan, matching issues are flipped from open to accepted and tagged with the
sub-rule that justifies them. Match key is (category, repo-relative file, exact before line) — if a heading is intentionally edited, its accept-list
entry stops matching and the issue correctly returns to open for re-review.
# Default: accept-list applied, summary shows matched + stale counts
python3 binder/tools/audit/scan.py --scope vol1 -v
# Report every issue, ignoring the accept-list
python3 binder/tools/audit/scan.py --scope vol1 --no-accept-list -v
# Use a different accept-list file (e.g. a draft to iterate on)
python3 binder/tools/audit/scan.py --scope vol1 --accept-list /tmp/draft.json
Scan usage
All commands are from the repo root.
python3 binder/tools/audit/scan.py --scope vol2 --verbose
python3 binder/tools/audit/scan.py --scope vol1 --output vol1-ledger.json --verbose
Produces audit-ledger.json (or the path given by --output).
Check categories
| Category | Rule | Notes |
|---|---|---|
vs-period |
§10.10 | Bare vs in prose |
compound-prefix-closeup |
§10.8 | Strict 6-term list, no extrapolation |
percent-symbol |
§10.2 | HTML attribute filter (width=N%) |
lowercase-prose-references |
§10.4 | Hand-written "Chapter 12" |
acknowledgements-spelling |
§10.7 | British → American |
binary-units-in-prose |
§1 | Detection only |
h3-titlecase |
§10.9 | Per-heading judgment required |
Validation anchors
Scan times on a cold run from the repo root:
$ python3 binder/tools/audit/scan.py --scope vol1 -v
Total: 629 issues across 34 files (0.4s)
$ python3 binder/tools/audit/scan.py --scope vol2 -v
Total: 969 issues across 39 files (0.4s)
Steady-state anchor (2026-04-08)
| Category | vol1 open | vol1 accepted | vol2 open | vol2 accepted |
|---|---|---|---|---|
| vs-period | 0 | 0 | 0 | 0 |
| compound-prefix-closeup | 0 | 0 | 0 | 0 |
| percent-symbol | 0 | 0 | 0 | 0 |
| lowercase-prose-references | 0 | 0 | 0 | 0 |
| acknowledgements-spelling | 0 | 0 | 0 | 0 |
| binary-units-in-prose | 0 | 0 | 0 | 0 |
| h3-titlecase | 61 | 0 | 29 | 0 |
| concept-term-capitalization | 19 | 0 | 62 | 0 |
| abbreviation-first-use | 163 | 0 | 111 | 0 |
| TOTAL | 243 | 0 | 202 | 0 |
Item D uses file-level exclusions for glossary.qmd (glossaries are
definitions, not first uses) and excludes the SIFT homonym (CV meaning vs
fault-tolerance meaning).
Reproduce with python3 binder/tools/audit/scan.py --scope vol1 -v.
Run the detector self-tests with:
PYTHONPATH=binder/tools python3 binder/tools/audit/checks/h3_titlecase.py
PYTHONPATH=binder/tools python3 binder/tools/audit/checks/concept_term_capitalization.py
PYTHONPATH=binder/tools python3 binder/tools/audit/checks/abbreviation_first_use.py
Expect 41/41 passed, 32/32 passed, and 17/17 passed.
Adversarial test coverage
protected_contexts.py: 14 adversarial tests covering bold definitions, callout titles, table headers, sentence starts, index entries, @-refs, citations, footnote refs, fig-cap attributes, inline code, and inline math.compound_prefix.py: 21 tests covering the strict 6-term list, domain-compound preservation, acronym/proper-noun continuation, and case preservation.
Run the adversarial tests inline with each check module during development.