AA b19: Matheo citation infrastructure — do it right, site-wide#

Status: OPEN
Scope: site-wide. Belongs in this registry (not beside any one paper) because it touches every Matheo paper and the shared .bib files.
Origin: migrated 2026m08d04 from AHA/aa-open-tasks.md entry AA-matheo-cite-migration-a1 (k4 Todo, s3 ShortTerm), itself deferred from the 2026m07d14 B1/B2 work on the AI Safety Wager proposal. Re-measured 2026m07d16 and again 2026m08d03–04.
Also referenced by: CLAUDE.md (Citation and Paper Naming Conventions –> “AnyAims (deferred follow-up)”), which carries only a 4-line stub. This file is the entry of record; the stub points here.

Warning

Read item 8 before touching any ``.bib`` file. A duplicate key does not error — it silently truncates the file and drops every entry after it, site-wide, with exit code 0. This sweep involves moving keys between .bib files, which is exactly how the duplicate gets created. Run make check-bib first and again after.

Task list#

k

s

Task

Notes

k5

s3

1. Fix the cross-page capture (bibliography-management.md Rule D).

Migrate every per-page .. bibliography:: still using :filter: cited and True to :filter: docname in docnames. Seven pages still capture as of 2026m08d04: b11-form-pet-mmv5, b12-theophil-e7day-mmv5, b12-socpsy-e7day-mmv5, b12-math-e7day-mmv5, b12-syseng-e7day-mmv5, b14-math-jub-mmv5, b15-math-deadlock-mmv5. Bake the correct filter into scripts/gen-matheo-floor.py / AHA/matheo-floor-pour.md so regenerated floors inherit it. Demonstrated harm: until 2026m08d04 the b16 OOv3 draft had no bibliography of its own, and all 31 of its :cite: calls rendered into b15-math-deadlock-mmv5’s reference list — a different paper.

k5

s3

2. Migrate the deprecated ``Matheo-N`` keys.

116 occurrences across 22 files (measured 2026m08d04): Matheo-2 (48), Matheo-1 (25), Matheo-6 (14), Matheo-5 (12), Matheo-4 (7), Matheo-7 (6), Matheo-8 (2), Matheo-3 (2). Migrate onto the Matheo-b11..``Matheo-b21`` mechanism (all 11 keys already exist). b16 OOv3 is clean and not affected.

ATTEMPTED AND WITHDRAWN 2026m09d11 — see LLog — Push-readiness audit: what stands between two months of work and the public site. The 8 deprecated-key sites in study/matheo/b15/b15-math-deadlock-mmv5.rst were migrated in place, and LLoL withdrew the change before it could be committed: editing the published MMv5 copy in source/study/matheo/ would set a precedent that future paper revisions live in the public study folder rather than in a HELL variant built to absorb them. The work is preserved in a git stash for later redoing as a HELL variant.

So this task is still fully OPEN, and the constraint is now explicit: when the Matheo-N → Matheo-bNN migration is done, it must be done in a new HELL variant of each affected paper, never as an in-place edit of the poured MMv5 floor.

What this task no longer needs to fix, however, is the reader-facing damage. The bibliography repair (task 1 note below / balospe-refs.bib, 2026m09d11) resolves every deprecated key and gives each the canonical short author line, so the b15 page renders correctly with its original citations untouched. Migration is now hygiene only.

PLAN CORRECTION — do NOT delete the deprecated entries. This row previously said “THEN delete Matheo-1 / Matheo-2 … Balospe-1, YahEtAl-a1”. Deleting them would re-break every one of those ~115 archive sites, which may not be edited to point elsewhere — each would render an empty [] with no build warning. The entries were therefore repaired and completed instead: Matheo-3…Matheo-8 and SD4 were added, and all now carry the canonical short author line and the live bNN title and URL. They are permanent archive-compatibility shims, not leftovers. Deletion is off the table unless the archive policy changes.

k5

s3

3. Settle the inline display style for :cite:`Matheo-bNN`.

Either a key-label reference style so it renders “Matheo-b17” rather than “(Yah et al., 2026)” — or keep :doc: as the permanent inline standard and use matheo-refs.bib only for list-only reference sections. Decide and document in bibliography-management.md. Evidence from practice: b16 OOv3 uses :doc: 16 times and (until 2026m08d04) :cite: once; the :cite: one rendered as “Loewe, L., 2026” and was converted to :doc: for internal consistency — provisionally, without prejudice to this decision.

Input added 2026m09d11: the “(Yah et al., 2026)” rendering noted above came from the author field, not the display style — the deprecated entries carried the full twelve-word authorship chain, which rendered inline in body text. That is now fixed at the source for every entry. The display-style decision is therefore narrower than it looked: it is now only about whether a key-label style is preferable to a clean author-year one, not about suppressing a twelve-word string. Also newly testable: the canonical Matheo-bNN entries put their link in url, which per feedback_bibtex_note_renders often does not render for @misc; b15 is the first paper to cite them, so this can now be checked in the built page.

k4

s3

7. Fix the live empty ``[]`` citations.

check-bib.py --built finds 8 pages carrying unresolved :cite: that render as a bare []. Includes the PUBLISHED floor page study/matheo/b15/b15-math-deadlock-mmv5 (5), live to readers now. Also hell/mm/b/16/mmv1/b16-riskymad_mmv1 (17), .../mmv1/b16-riskymad-intro_mmv1 (8), hell/ll/study/b/12/study_ll_2026m04d05_b12-revision-material-for-mmv3 (7), hell/ll/study/b/16/study_ll_2026m04d09_b16-riskymad-writing-llog (5), hell/mm/b/15/math/mmv3/b15-structural-deadlock_mmv3 (5), .../mmv2/... (3), hell/mm/b/11/mmv3/b11-pet-intro_mmv3 (1). The b15 mmv5 keys are Matheo-4, Matheo-6, Matheo-7, SD4 — these exist in no .bib at all, so they render as [] rather than as a wrong link.

k3

s2

4. Fix the stale count in ``AHA/matheo-series-pdf.md``.

Says “33 / 29+4 held”; should be 32, HELD now empty.

k3

s1

5. Consider generating B1 from ``gen-matheo-floor.py``.

_templates/include-file/matheo-series-reflist.rst is hand-maintained; generating it would stop it drifting.

k2

s1

10. Sweep the remaining undefined substitutions.

|MADI| and |checkmark| seen in build logs, not yet swept. Same silent-failure family: on 2026m07d16 |le| and |deg| were found defined nowhere, and |deg| was broken in the published study/matheo/b16/b16-form-riskymad-mmv5, silently dropping the degree sign from its 5–10 °C temperature drop. Both fixed; the convention is |leq|.

Standing hazards — read before doing any of the above#

6. A checker exists: ``scripts/check-bib.py`` (``make check-bib``, also in ``make lint``). It reports duplicate keys, entries dropped from the build cache, and unresolved :cite:. Run it first — it turns this sweep from “grep and hope” into a list with an exit code.

8. A duplicate key SILENTLY TRUNCATES a ``.bib`` file. Documented as Rule E in AHA/bibliography-management.md. It does not error. pybtex stops ingesting at the duplicate and drops every entry after it, site-wide. Verified: one duplicate (Levin2012, added to b16-nuclear-risk.bib while already in references.bib) reduced the build cache from 136 keys to 102 — destroying Loewe2006, Luhmann1995, Maslow1943, MartinLof1984 and 30 others on every page, with exit code 0. The old advice that duplicates “fail loudly at build” was false and has been corrected in the AHA and in both .bib headers.

9. There is no ``bibtex.pickle``. The parse cache lives in build/html/en/.doctrees/environment.pickle under domaindata['cite']['bibdata'], is mtime-keyed per .bib, and rm bibtex.pickle does nothing. “Missing from build cache” has two causes that look identical: a stale cache (harmless — a rebuild clears it) or truncation (real loss — survives a rebuild). check-bib.py says which.

Testing note. Needs make clean && make html to test Rule D: incremental builds cache the wrong link, so an incremental build will appear to confirm a fix that has not happened.

Current bibliography inventory (2026m08d04)#

File

Entries

Scope

references.bib

91

cross-cutting; cited by two or more papers

b16-nuclear-risk.bib

24

b16 only

b19-epidemiology.bib

12

b19 only

matheo-refs.bib

11

the Matheo-b11..``Matheo-b21`` series keys

balospe-refs.bib

7

site refs; holds the deprecated Matheo-1 / Matheo-2 / Balospe-1

total

145

what check-bib reports

Promotion rule (from the b16-nuclear-risk.bib header): when a ref in a paper-local file becomes cited by a second paper, move it to references.bib. Keys are project-global. Applied 2026m08d04 to Kemp2025.

See also#

On this page
Recent Posts
Tags