LLog b14 (infra): wwv-sgir RST-citations → sphinxcontrib-bibtex migration#

Date: 2026m04d27
Mode: EDEN (per .claude/mode, confirmed by prompt: “Mode: EDEN”)
Effort: Max (per .claude/effort-level, confirmed by prompt: “Effort: max”)
Assessor: Claude Opus 4.7 Max (ClaOp47Max)
VVN of this llog: infra-llog-wwv-sgir-bibtex-dv_ClaOp47Max_OOv1r0p0_2026m04d27_16h32
Branch: 7-paper-guard-against-echo-chambers

Verbatim prompt#

Please do this: (the prompt in AA b16):    Dedicated session: resolve the toctree-conflict for
``source/matheology/hell/mm/b/19/si/wwv-sgir-evolvix-study-dv_llol_oov1_2026m04d17.rst``
so it can be re-included in the b19 paper's toctree without
triggering Sphinx duplicate-citation-target warnings.

Mode: EDEN. Effort: max.

THE PROBLEM
-----------
The current b19 ``index.rst`` (lines 34-35) shows:

    .. Removed from toctree to prevent PDF citation conflicts:
    .. si/wwv-sgir-evolvix-study-dv_llol_oov1_2026m04d17

Two files share the b19 directory tree but use *different* citation
systems:

- ``b19-sgir_basic-gap-of-germs-2020-epidemiology-oov1_2026.rst``
  uses sphinxcontrib-bibtex via ``:cite:`X``` (e.g.
  ``:cite:`PrototypeEvolvixCompiler``` after the 2026m04d27
  migration), with the bibliography entries living in
  ``source/_bib/references.bib`` and ``source/_bib/b19-epidemiology.bib``.
- ``si/wwv-sgir-evolvix-study-dv_llol_oov1_2026m04d17.rst`` uses
  RST-native footnote-citation syntax via ``[X]_`` for references
  and ``.. [X] ...`` definitions inline at the end of the file
  (e.g. ``.. [PrototypeEvolvixCompiler] Loewe, L. (2015). ...``).

When both files appear in the same toctree, Sphinx may emit
duplicate-target warnings because the ``[X]`` HTML target is
produced by both citation systems independently.

THE GOAL
--------
Convert the wwv-sgir file to use sphinxcontrib-bibtex
(``:cite:`X``` syntax) so its citations resolve through the same
bibliography pipeline as b19. After conversion, re-add the file
to b19's index.rst toctree and confirm the build is clean.

STEPS
-----
1. Read ``source/matheology/hell/mm/b/19/si/wwv-sgir-evolvix-study-dv_llol_oov1_2026m04d17.rst``
   and inventory all RST-native citations: every ``[X]_`` reference
   and every ``.. [X] ...`` definition.
2. For each cited key, check whether it already exists in
   ``source/_bib/references.bib`` or ``source/_bib/b19-epidemiology.bib``.
   If it exists, the conversion is a syntax change only.
   If it does not exist, add a new entry to whichever bib file fits
   its scope (cross-cutting → references.bib; b19-only → b19-epidemiology.bib).
3. Replace ``[X]_`` with ``:cite:`X``` throughout the file. Delete
   the ``.. [X] ...`` definition lines at the bottom (the bibliography
   will now be rendered via sphinxcontrib-bibtex's ``bibliography``
   directive at the appropriate place in the file).
4. Add a ``bibliography`` directive at the bottom of the file:

      .. bibliography::
         :filter: docname in docnames

   to render only the citations actually used in this file.
5. Re-add the file to b19's ``index.rst`` toctree (uncomment the
   lines 34-35).
6. Run ``make dev`` (or ``make html`` for the full multi-language
   build) and confirm there are no duplicate-citation warnings.
   Report any warnings honestly --- do not silence them.

CONSTRAINTS
-----------
- Per LLoL's standing rule (CLAUDE.md): NEVER delete content files;
  if the wwv-sgir file is deemed obsolete after conversion, move
  it to a local ``HH/`` HistoryHeap folder for human review, do not
  delete.
- Per CLAUDE.md Language Rules: use "test"/"check" not
  "validate"/"verify"; YYYYmMMdDD dates; OK/NOT OK not PASS/FAIL.
- Do NOT silently change the citation key for ``EvolvixCompiler``
  in the wwv-sgir file --- the canonical key in references.bib is
  now ``PrototypeEvolvixCompiler`` (renamed 2026m04d27); update the
  wwv-sgir references to match.
- The wwv-sgir file is dated 2026m04d17 in its filename; that is
  historical metadata. Update the file's internal VVN to reflect
  the conversion (e.g. ``dv_ClaOp47Max_OOv2r0p0_2026m04dXX_HHhMM``)
  when you record the new state, but do not rename the filename
  unless LLoL approves.

OUTPUT
------
- Updated wwv-sgir file with bibtex-style citations.
- Possibly new entries in references.bib or b19-epidemiology.bib.
- Updated b19 index.rst with the file re-added to the toctree.
- A short report listing: which citations were converted, which
  bib entries were added (if any), the build outcome (OK / NOT OK
  with details), and any open items for LLoL.


Cross-references
==================

- :doc:`/_POST/AnyAims/index` --- AA registry (parent)
- :doc:`/matheology/hell/mm/b/19/index` --- the b19 paper home
- :doc:`/matheology/hell/mm/b/19/b19-sgir_basic-gap-of-germs-2020-epidemiology-oov1_2026`
  --- the paper itself
- :doc:`/_POST/AnyAims/b/11/b11-evolvix-integration-into-paper-sequence`
  --- companion AA on Evolvix integration across the broader paper sequence

Citation inventory (Step 1)#

Twelve unique citation keys were found in the wwv-sgir file:

RST-native citation inventory#

Key (in wwv-sgir as [X]_)

References in body

First-occurrence line(s)

EvolvixCompiler

2

22, 1191

Talic2021

1

98

Ferguson2020

1

100

Giordano2020

1

100

Kissler2020

1

101

KermackMcKendrick1927

1

106

Caplan2020

1

138

Mosley2025

1

138

Mallet2012

2

275, 323

Ehlert2014

3

435, 441, 1065

Stutt2020

1

610

MeyerowitzKatz2020

1

875

All twelve keys had .. [X] ... definitions in the file’s References section (lines 1250–1323) prior to the migration.

Bib coverage check (Step 2)#

Comparison against the bib files:

  • source/_bib/b19-epidemiology.bib already contained: Caplan2020, Ferguson2020, Giordano2020, Kissler2020, MeyerowitzKatz2020, Mosley2025, Stutt2020, Talic2021 (8 keys).

  • source/_bib/references.bib already contained: Ehlert2014, KermackMcKendrick1927, Mallet2012, PrototypeEvolvixCompiler (the renamed key for the 2015 prototype Evolvix compiler — 4 keys).

Total: 12 of 12 keys already in the bib pipeline. No new bib entries were required. The conversion is purely a syntax change, with the single key rename EvolvixCompiler → PrototypeEvolvixCompiler applied at both occurrences (lines 22 and 1191) per CLAUDE.md constraint (“Do NOT silently change the citation key… the canonical key in references.bib is now PrototypeEvolvixCompiler”).

Conversion (Step 3)#

Twelve search-and-replace operations on the wwv-sgir file:

Citation conversions#

Before

After

[EvolvixCompiler]_

:cite:`PrototypeEvolvixCompiler` (key renamed)

[Talic2021]_

:cite:`Talic2021`

[Ferguson2020]_

:cite:`Ferguson2020`

[Giordano2020]_

:cite:`Giordano2020`

[Kissler2020]_

:cite:`Kissler2020`

[KermackMcKendrick1927]_

:cite:`KermackMcKendrick1927`

[Caplan2020]_

:cite:`Caplan2020`

[Mosley2025]_

:cite:`Mosley2025`

[Mallet2012]_

:cite:`Mallet2012`

[Ehlert2014]_

:cite:`Ehlert2014`

[Stutt2020]_

:cite:`Stutt2020`

[MeyerowitzKatz2020]_

:cite:`MeyerowitzKatz2020`

After replacement, a grep for \[[A-Za-z][A-Za-z0-9_]*\]_ returned no matches: all RST-native citation references are gone.

Bibliography directive (Step 4)#

The 12 .. [X] ... definitions (lines 1250–1323) were removed and replaced with:

References
=============

.. bibliography::
   :filter: docname in docnames

This matches the directive used in the b19 main paper at line 1879 of b19-sgir_basic-gap-of-germs-2020-epidemiology-oov1_2026.rst, so the two files now resolve through the same bibliography pipeline.

VVN bumped (file metadata)#

The wwv-sgir file’s VVN was bumped from wwv-sgir-dv_ClaOp47Max_OOv1r0p1_2026m04d20_16h20 to wwv-sgir-dv_ClaOp47Max_OOv2r0p0_2026m04d27_16h32 to reflect a material content-system change (a major version bump v=1→2 is appropriate because the citation infrastructure is a structural change visible to readers of the rendered output, not a cosmetic edit). The filename was preserved per CLAUDE.md constraint (“do not rename the filename unless LLoL approves”).

The :orphan: directive at line 1 was also removed because the file now lives inside the b19 toctree and :orphan: would conflict with that.

Toctree update (Step 5)#

In source/matheology/hell/mm/b/19/index.rst, the previous commented-out lines:

.. Removed from toctree to prevent PDF citation conflicts (resolution prompted in AA b16):
.. si/wwv-sgir-evolvix-study-dv_llol_oov1_2026m04d17

were replaced by an active toctree entry:

   si/wwv-sgir-evolvix-study-dv_llol_oov1_2026m04d17
.. wwv-sgir file rejoined toctree 2026m04d27 after migration to sphinxcontrib-bibtex
.. (citations now resolve through the same bibliography pipeline as b19 main paper).

Build outcome (Step 6) — OK#

make dev ran to completion with 15 warnings total:

  • 0 duplicate-citation warnings — the goal of this task is met.

  • 0 duplicate-target warnings — the toctree-conflict is resolved.

  • 13 image warnings of the form WARNING: image file not readable: _file/.../webp/figNN-*.webp, one per figure 1–13. These are pre-existing: the wwv-sgir file references .webp thumbnails that were never generated. The file was previously :orphan:, so Sphinx still built it and would have emitted the same warnings under the previous setup. Out of scope for this task; flagged here for LLoL’s awareness as a separate AA item.

  • 2 unrelated warnings about b13-evolvix-zenodo-and-post-infrastructure-llog.rst (“document isn’t included in any toctree”) and a stale [Matheo-2-m-v2] citation reference in b13-e7he_mmv2_2026m04d08.rst. Both pre-existing, neither caused by this task.

Final build status: build succeeded, 15 warnings. HTML output is in build/html/en. The wwv-sgir page now renders with a unified bibliography at the bottom, and the b19 toctree includes both the main paper and the supplementary file without conflict.

EDEN classification#

This task lives on a Knife Edge KE-1: the only path that resolves the toctree-conflict without losing the wwv-sgir content is the unification onto the bibtex pipeline. Three rejected alternatives:

  1. Leave the file as ``:orphan:`` indefinitely. Rejected: the file contains the supplementary detail that supports the b19 paper’s methods section; readers who follow the SI link from the main paper would land on a page that is not navigable from the paper’s own toctree — structurally hidden content is BABL (“blindly assuming blind leveraging” of orphan-status to dodge a real conflict).

  2. Roll the b19 main paper back to RST-native citations. Rejected: the rest of the project (including conf.py, bibtex_bibfiles auto-discovery, the b19 main paper, and likely future papers b11–b18) standardizes on sphinxcontrib-bibtex; rolling back one paper to be the odd one out is OSCR (over-Simplifying the single page at the cost of over-Complicating the project).

  3. Strip the bibliography from wwv-sgir entirely. Rejected: destroys reader-facing reference information without a forwarding pointer; violates CLAUDE.md’s “NEVER delete content files” rule and would orphan the rendered citations.

The chosen path (Option 1: convert to bibtex) is gentle (no reader sees a regression), kind (preserves all 12 references with full metadata), and reasonable OLT (extensible: future SI files in this or other papers follow the same pattern).

Open items for LLoL#

  1. Missing ``.webp`` thumbnails (13 figures). These pre-existing warnings are not caused by this task but become more visible now that the file is in the toctree. Consider generating the thumbnails or removing the .webp references; suggest a separate AA entry.

  2. AA b16 status update. The AA b16 task list at source/_POST/AnyAims/b/16/ should be marked “DONE” for this sub-task; the AA registry index in source/_POST/AnyAims/index.rst may need a parallel update. Also update source/matheology/heaven/study/aaa.rst if this work appears there per the AAA QuickRef rule.

  3. infra/index.rst is stale. The Next free number admonition at line 21 of source/matheology/hell/ll/infra/index.rst claims “b12” is next free, but b12, b13, and now b14 all exist. Suggest updating the index in a follow-up to add the b12, b13, b14 entries to its toctree (which would also clear the b13 “isn’t included in any toctree” warning).

  4. Removed ``:orphan:`` directive. This was a judgment call. Strictly speaking, an :orphan: page that is also in a toctree triggers a Sphinx warning, so the directive had to go. Flagging here so LLoL can confirm.

Summary (BABL → ZION)#

(0) BABL danger considered. The pre-task state (file marked :orphan: and excluded from the toctree with a comment “Removed from toctree to prevent PDF citation conflicts”) was BABL by Friendly OSCR: the surface looked clean (no warnings during build), but the substance had drifted (the SI file was structurally invisible to readers of the main paper). The risk of leaving this in place was a silent split between “what the paper says exists” and “what the toctree shows” — exactly the kind of LIE/SIN gap that builds an echo chamber over time.

(1) ZION path taken. Convert the SI file to the same bibtex pipeline as the main paper, re-include in the toctree, run the build, report the result. The conversion is reasonable (extensible to all future SI files), kind (preserves every reference with full metadata), gentle (no reader-facing regression). The build confirms the change holds: build succeeded, 15 warnings, none of which are duplicate citations or duplicate targets.

Result code: OK. The toctree-conflict named in AA b16 is resolved.