.. meta:: :description: AA b19 --- Do the Matheo citation infrastructure right, site-wide: cross-page bibliography capture, deprecated Matheo-N keys, inline display style, and the duplicate-key truncation hazard. :keywords: AnyAims, AA b19, Matheo, citations, bibtex, sphinxcontrib-bibtex, cross-page capture, duplicate keys, check-bib :author: LLoL as Laurence Loewe of Laodicea, ClaudeOp46-50Max, and Everyone .. _post-aa-b19-matheo-citation-infrastructure: **************************************************************************************** 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 ============= .. list-table:: :header-rows: 1 :widths: 5 5 42 48 * - 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 :ref:`hell-ll-infra-b47-push-readiness-audit-llog`. 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`` |rarr| ``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) ============================================= .. list-table:: :header-rows: 1 :widths: 40 15 45 * - 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 ========== - :doc:`/_post/aa/index` --- AA registry (parent), and the placement rule - :ref:`hell-mm-b16-aa-finalizing` --- the b16 paper's own list; its bibliography row depends on decisions 1 and 3 above - ``AHA/bibliography-management.md`` --- Rules A, B, C, D, E, N, 0 - ``AHA/aa-anyaims-sorting.md`` --- which AA file lives where, and why