feat: products/ output layout + PDF/UA-1 validation gate

[agiacalone]

Summary

Two changes, both test-first. +23 tests; full suite 191 green (npm test).

1. Output hygiene — products/ layout + intermediate cleanup ✅ complete

Generated artifacts and pdflatex's scratch files were landing in the topic root beside the kept _lecture_main.md source, drifting the classes-layout-doctrine (hit intro_to_compsec + 999/ac_measurement_principles).

• Default --out is now a products/ subdir beside the source (lib/out-dir.js); explicit --out still honored verbatim.
• compileLatex sweeps .aux/.log/.out/.nav/.snm/.toc after each successful compile, keeping only .tex + .pdf (lib/latex-clean.js; never touches the .tex/.pdf or other decks' files).
• products/ added to .gitignore.
• Verified end-to-end on the example lecture: artifacts in products/, topic root clean, no stray intermediates.

2. ADA Title II / WCAG audit chain — advances #7

PDF/UA-1 validation gate (Phase 3). The pre-generation stages check the source; this checks the compiled PDFs.

• lib/a11y/pdfua.js: veraPDF PDF/UA-1 deep check when present, else a pdfinfo Tagged: smoke-check fallback. A tagged PDF passes the smoke-check but its report row says "smoke-check only — install veraPDF" — a fallback pass is never mistaken for a full PDF/UA pass (no silent pass).
• generate.js appends a pdf-ua stage to a11y-report.json and gates the build (exit 1) on any untagged artifact.
• Pure interpreters + orchestration unit-tested (lib/a11y/pdfua.test.js, 8 tests). 5/5 example PDFs pass on TL2026.

Table header /TH tagging (Phase 2 polish — table semantics). Found and pikepdf-verified the working mechanism on TL2026 (\thead{} was a red herring):

• \DocumentMetadata{…testphase={phase-III,table}} + group-scoped \tagpdfsetup{table/header-rows={1}} → header row tags as /TH, data rows /TD, and the group scope keeps non-header layout tables (e.g. the Cornell cue/notes table) at /TD with no leak to later tables.
• Applied to texComparisonTable + cornellComparisonTable, unit-tested.
• Caveat (intentionally surfaced): those comparison-table emitters aren't yet called by the live markdown-monolith generators, so the recipe is correct + ready but no shipping artifact emits /TH yet — wiring them in is a follow-up.

Scope / what this does NOT do

Advances #7 — does not close it. Remaining on the issue:

• Phase 4 — CI enforcement over examples/ artifacts.
• Phase 5 — changelog/AGENTS.md doctrine propagation.
• veraPDF install (userspace Java) so the deep check actually runs — the gate is wired and auto-detects it on PATH.
• Comparison-table wiring so the /TH mechanism fires on real artifacts; then heading-hierarchy + figure-actualtext, driven against veraPDF.

Docs

• CHANGELOG.md — entries under [Unreleased] (Fixed: output hygiene; Added: PDF/UA gate, table /TH).
• docs/plans/wcag-audit-pass-plan.md — Phase 3 marked done, and the verified /TH recipe recorded (incl. the two auto-mechanisms that don't work, so they aren't retried).

Test plan

• npm test → 191 passing.
• npm run check → clean.
• node generate.js --main examples/file_systems_abstraction_lecture_main.md → artifacts in examples/products/, ✓ pdf-ua: 5 PDF(s) tagged (pdfinfo smoke-check), build gated.

🤖 Generated with Claude Code

[agiacalone]

veraPDF installed — deep check now runs, and it surfaced the real state

Installed veraPDF 1.30.2 (userspace, ~/verapdf/ → ~/bin/verapdf) and pointed the gate at it. Honest result: every example artifact is tagged but fails full PDF/UA-1 (4–6 rules each).

Failing rule classes (the remediation backlog, now documented in the plan doc):

1. PDF/UA identifier missing in XMP (clause 5)
2. dc:title missing + DisplayDocTitle not true (clause 7.1)
3. PDF header EOL nit (clause 6.1)
4. Untagged real content — fancyhdr header/footer rules need /Artifact marking (clause 7.1 t9)

Gate behavior corrected (commit 3522ddc)

That finding exposed a bug in my first commit: the gate blocked on any non-pass, so installing veraPDF broke node generate.js (exit 1) for every lecture. Fixed:

• Blocking invariant = tagged-presence — an untagged PDF fails the build (exit 1). Unchanged intent.
• veraPDF PDF/UA-1 verdict = advisory (row.ua1) — logged loudly + written to a11y-report.json, never flips the exit code. Full PDF/UA-1 compliance is remediation work that shouldn't block lecture generation. A future --strict-a11y flag can opt into blocking.

node generate.js now exits 0 with the advisory surfaced; suite 193 green. The PDF/UA-1 remediation is tracked as a follow-up (still advances #7, doesn't close it).

[agiacalone]

PDF/UA-1 metadata remediation — driven against veraPDF (commit 9eb86a1)

Found the recipe and applied it to both preambles, red→green against veraPDF 1.30.2:

• \DocumentMetadata{…pdfstandard=ua-1,pdfversion=1.7,…} → PDF/UA-1 XMP identifier + forces the PDF-1.7 header (default was 2.0)
• \hypersetup{pdftitle={<title>},pdfdisplaydoctitle=true} → dc:title + DisplayDocTitle

Result: 4–6 failed rules each → quiz + quiz-key fully PDF/UA-1 compliant (0 failures); lecture-notes + Cornell handout + key down to 1 rule (clause 7.1 t3 — colortbl \cellcolor/\columncolor + an mdframed fill draw untagged decorative backgrounds; known colortbl+tagging limitation, the final remediation step). Suite 196 green.

[agiacalone]

Roadmap P1–P5 cleared + audit documentation

Pushed the full accessibility roadmap on top of the metadata remediation:

• P1 — GFM comparison tables → tagged /TH (86a1ab1): parser captures pipe tables (tables/tablesForSection), lecture-notes + Cornell generators render them through the /TH emitters, example gains a Hard-link vs Symlink table under §III. pikepdf confirms TH=3 — the /TH mechanism is no longer latent.
• P3 — --strict-a11y (3fa3ab8): untagged always blocks; PDF/UA-1 non-compliance blocks only under strict (advisory by default). Pure evaluatePdfUaGate, unit-tested.
• P4 — CI (bb45bad): .github/workflows/a11y.yml installs TeX Live 2025 + veraPDF, default gate blocking + --strict-a11y informational (so the toolchain-gated rule doesn't permared CI). Needs one live validation run.
• P5 — changelog philosophy (4b30d00 here; lectern docs: changelog philosophy + technical-audience sweep lectern#18, oracle agiacalone/oracle#31).
• Audit doc — docs/ACCESSIBILITY.md: the authoritative ADA Title II / PDF/UA-1 compliance record (scope, architecture, blocking model, evidence, honest status, maintenance).

206 tests green; build exits 0. P2 (last PDF/UA-1 rule) remains toolchain-gated and documented; the advisory gate + docs/ACCESSIBILITY.md §5 carry the honest status. This branch is ready for review/merge.