ci: pin pandoc to 3.10 for reproducible reference builds

.github/workflows/ci.yml

@@ -47,8 +47,17 @@ jobs:
       - name: Shellcheck build script
         run: shellcheck scripts/build-reference.sh
 
-      - name: Install pandoc
-        run: sudo apt-get update && sudo apt-get install -y pandoc
+      # Pin pandoc to the version the committed reference was authored with, so
+      # regeneration is byte-reproducible. Distro apt pandoc floats by release
+      # (Ubuntu noble ships 3.1.3) and its Markdown output differs cosmetically
+      # from 3.10, which would produce false drift warnings.
+      - name: Install pinned pandoc 3.10
+        run: |
+          curl -sSL -o /tmp/pandoc.tar.gz \
+            https://github.com/jgm/pandoc/releases/download/3.10/pandoc-3.10-linux-amd64.tar.gz
+          echo "e0f8af62d0f267d22baa5bcefe6d5dda3a097ccc60de794b759fe03159923244  /tmp/pandoc.tar.gz" | sha256sum -c -
+          tar xzf /tmp/pandoc.tar.gz -C /tmp
+          echo "/tmp/pandoc-3.10/bin" >> "$GITHUB_PATH"
 
       - name: Regenerate reference from live W3C source
         run: ./scripts/build-reference.sh

AGENTS.md

@@ -28,8 +28,12 @@ A single agent skill (`SKILL.md`) plus the verbatim WCAG 2.2 specification it re
 
 ## Workflow to update the spec
 
+Use **pandoc 3.10** to reproduce the committed reference byte-for-byte. Other
+versions produce a large cosmetic no-op diff (still valid, but noisy). CI pins
+3.10 via the static binary; match it locally.
+
 ```bash
-./scripts/build-reference.sh     # fetch + convert + re-header
+./scripts/build-reference.sh     # fetch + convert + re-header (pandoc 3.10)
 node scripts/validate.mjs        # confirm counts, date, 4.1.1 absent
 # update SKILL.md if criteria changed, bump CHANGELOG + version
 ```

CHANGELOG.md

@@ -14,6 +14,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the clone-to-setup path is exercised on every push and PR.
 - Weekly scheduled CI run to surface upstream WCAG spec drift.
 
+### Fixed
+
+- Pin CI pandoc to 3.10 (static binary, sha256-verified) instead of floating
+  distro apt (3.1.3). Distro pandoc converts the same HTML to cosmetically
+  different Markdown, producing a false drift warning; pinning makes reference
+  regeneration byte-reproducible so the drift check fires only on real spec
+  changes.
+
 ## [0.1.0] - 2026-07-10
 
 ### Added

scripts/build-reference.sh

@@ -2,6 +2,11 @@
 # Regenerate references/wcag-2.2-full.md from the live W3C source.
 # Requires: curl, pandoc. Preserves all normative text; strips HTML wrappers;
 # re-applies the W3C attribution header.
+#
+# Reproducibility: the committed reference is authored with pandoc 3.10. Other
+# pandoc versions convert the same HTML to cosmetically different Markdown
+# (different escaping/list markers), which passes validate.mjs but shows as a
+# large no-op diff. Use pandoc 3.10 to reproduce the committed file byte-for-byte.
 set -euo pipefail
 
 SRC="https://www.w3.org/TR/WCAG22/"
@@ -14,6 +19,8 @@ trap 'rm -f "$TMP_HTML" "$TMP_MD"' EXIT
 command -v curl >/dev/null || { echo "curl not found" >&2; exit 1; }
 command -v pandoc >/dev/null || { echo "pandoc not found" >&2; exit 1; }
 
+echo "Using $(pandoc --version | head -1) (committed reference authored with pandoc 3.10)"
+
 echo "Fetching $SRC"
 curl -sL -A "Mozilla/5.0" "$SRC" -o "$TMP_HTML"