AA b18: build-warning gating and link guards — deferred tasks

VVN: aa-b18-build-warning-gating-dv_ClaOp50Max_MMv1r1p0_2026m09d11_12h55

Mode: EDEN (from file, not confirmed in-session)

Effort: Max per .claude/effort-level

Status: OPEN

Origin: the path-case fix session of 2026m08d03. These items were identified during that work and consciously not done, so the URL fix could ship. Full record: LLog — Path-case drift on the deploy server, and a consistent guard against silent link death (diagnosis) and TELES Sweep Manifest — path-case migration of 2026m08d03 (Double Caps in prose, lowercase in paths) (execution + corrections).

Background

On 2026m08d03 a directory-name case mismatch between git’s index and the working tree was found: source/FF and source/license/JoLi in git, source/ff and source/license/joli on disk. macOS is case-insensitive, so every local build resolved fine; the case-sensitive deploy server published the git spelling, and 563 :doc: references pointing at the lowercase paths died silently. The FeedbackFlow section and the Jonah License page were both unreachable at the URL the whole site linked to.

Two things let it survive for months:

1. Nothing compared git’s view of a path with the disk’s. Fixed — see scripts/check-paths.py (Check A), wired into make lint.

2. Nothing reads Sphinx’s warnings. SPHINXOPTS is empty, so an unresolvable :doc: warns and then renders as href-less plain text while the build stays green. NOT fixed — that is the k5 task below.

Cause 2 is the deeper one. Cause 1 produced this bug; cause 2 is why any silent-reference bug can ship. The guard added in that session covers three reference classes; warning gating would cover everything Sphinx itself sees.

Task list

k	s	Task	Notes
k5	s9	Test the ``_redirects`` splat rules immediately after the first deploy.	The 12 rules added on 2026m08d03 are the first use of ``:splat`` syntax in that file. If Cloudflare Pages does not handle it as expected, the old capitalised URLs 404 instead of 301 — a StayVS regression (published URLs revoked, not redirected). Curl each and expect 301: /en/FF/, /en/FF/system/, /en/FF/contact/, /en/FF/archive/, /en/FF/philosophy/, /en/license/JoLi/, /en/_POST/, /en/_POST/DD/, /en/_POST/AnyAims/, /en/good-news-pack/AA/, /en/matheology/hell/mm/b/14/OOv1/. Fallback if splats fail: enumerate the URLs explicitly. s9 because the window where an indexed URL silently 404s is the whole cost.
k5	s3	Turn on Sphinx warning gating (``-W –keep-going``) in CI.	This is the root-cause fix that the 2026m08d03 session deliberately staged behind the case repair — gating first would have meant 620 unresolved-:doc: hits and an abandoned flag. That backlog is now 0 outside HELL, so gating is affordable for the first time. Use ``-W``, NOT ``-n``. Nitpicky mode escalates missing domain cross-references (py/c/cpp) and does nothing for :doc:; an unresolvable :doc: already warns at default settings. Recommended shape: CI only at first, leaving local make dev ungated so writing is not slowed. Blocked by the row below.
k4	s3	Triage the 890-warning backlog far enough to make ``-W`` viable.	Full build 2026m08d03 (all 1291 docs): build succeeded, 890 warnings. Dominant categories: duplicate label mmv (~114), duplicate citation (~56), unknown document (32, all in HELL), document isn't included in any toctree (8), image file not readable (13). A blanket -W fails on all of these. Either fix the big categories first, or gate on a selected warning set — at minimum unknown document and toctree contains reference to nonexisting document, which are the two that hide dead links.
k3	s2	Decide what to do about the 32 ``unknown document`` warnings in HELL.	All 32 sit in frozen MockupModel archives and append-only llogs, pointing at pages that have since moved. A link that was correct when written is arguably correct as history, and editing it would falsify the record — so check-paths reports them without failing. But they also block a blanket -W. Options: exclude HELL from the gated build; add :orphan:-style suppression; or accept a documented allow-list. This is a genuine Grey Edge, not an oversight.
k3	s2	Fix the missing FF postfix includes in ``source/faq/index.rst``.	Lines 740 and 742 include /_templates/include-file/page-postfix-prelink.rst and page-postfix-postlink.rst, neither of which exists. Two CRITICAL messages every build. Pre-existing — present in ``HEAD`` before the 2026m08d03 session, deliberately not folded into a path-case commit. Four other files reference the same two paths; check whether they were renamed into footer/form-open-std/ or deleted.
k3	s1	Watch the PROBATIONARY TELES path-segment clause.	Added 2026m08d03 to TELES Renaming Policy — Mechanical Identifier Migrations. It lets ONE sweep llog with a complete manifest replace the per-file migration reports that the policy normally requires. LLoL’s instruction: there is virtually no experience with sweeps of this kind, so it must be watched and revoked if used too much. Frequency of use is itself the warning sign. Review after the next path-segment migration, or after 6 months, whichever comes first.
k4	s3	A public download button points at a PDF that was never committed.	source/study/matheo/b16/index.rst offers “Download OOv3 (PDF, 47 pages)” at /_file/pdf/hell/mm/b/16/b16-riskymad-waiting-time_oov3_2026m07d25_16h14m53-47pages.pdf. The file does not exist and is not in git history. It was built to build/pdf/…_2026m07d25_16h14m53.pdf (47 pages, timestamp matching the link exactly); the copy into source/_file/ was simply never made, so the link was written against the intended destination and the step was skipped. It is also stale: thirteen OOv3 builds sit in build/pdf/ and the paper has grown 47 |rarr| 68 pages (newest 2026m09d08_16h58m22, 3.7 MB). Fixing it needs LLoL’s decision on which build is authoritative, since committing one adds 3.7 MB and the page-count label must change with it. Found 2026m09d11; see LLog — Push-readiness audit: what stands between two months of work and the public site.
k2	s1	Confirm or correct the assessor nick ``ClaOp50Max``.	AHA/vvn-composition.md documents the pattern only up to ClaOp47Max. The 2026m08d03 session was Claude Opus 5 and used ClaOp50Max by extension of the ClaFa50Max (Fable 5) precedent — ClaOp5Max is the equally defensible alternative. Used in this file, in source/license/cyli/index.rst, and in both b45 llogs. Same open question as the last row of AA b17: b16 revision — the non-paper leftovers.
k2	s1	Extend ``check-paths`` coverage.	Known gaps, stated in AHA/linting.md: external link rot; _redirects target validity (136 rules, nothing checks their targets resolve); :ref: label resolution; case correctness inside locale/*.po. Add a fifth, measured 2026m09d11: raw </_file/…> hrefs are not checked against the filesystem at all. Check C covers :doc: refs only, so a download button pointing at a PDF that was never committed renders as a live link and 404s. One real instance found (row above); a scan of every non-HELL page found no others. AHA/linting.md needs the same addition. Literal-block detection is an indentation heuristic, not a real RST parser. A clean run means those three classes are clean — it is not a proof that all links work.

Guard-rail learned the hard way (2026m08d03)

Recorded here because it will otherwise be re-learned:

A clean ``make check-paths`` run is necessary but NOT sufficient after a bulk sweep. Findings inside source/matheology/hell/ are reported but do not fail, and that exemption — meant to protect frozen history — happily hid 12 stale toctree entries and one :doc: ref that the sweep itself had just broken in hell/mm/b/14/index.rst. Only make html surfaced them.

After any bulk path change, run both:

python3 scripts/check-paths.py --strict-hell   # no finding may name a swept path
make html                                      # inspect the new warnings

This is now condition 4 and 5 of the probationary clause in TELES Renaming Policy — Mechanical Identifier Migrations.

See also

• AnyAims (AA) Registry — AA registry (parent)

• LLog — Path-case drift on the deploy server, and a consistent guard against silent link death — diagnosis, independent check of the incoming brief, EDEN analysis

• TELES Sweep Manifest — path-case migration of 2026m08d03 (Double Caps in prose, lowercase in paths) — execution, full file manifest, appended corrections

• TELES Renaming Policy — Mechanical Identifier Migrations — the probationary path-segment clause

• AHA/linting.md — what check-paths covers and what it does not