From 27c8305b1a6bcbcde2019fbb3119f91306a9f390 Mon Sep 17 00:00:00 2001
From: Andrew Miller <andrew@84em.com>
Date: Fri, 10 Jul 2026 12:52:35 -0500
Subject: [PATCH] ci: pin pandoc to 3.10 for reproducible reference builds

Distro apt pandoc (3.1.3 on Ubuntu noble) converts the WCAG HTML to
cosmetically different Markdown than the 3.10 used to author the committed
reference, producing a false drift warning (100 insertions / 100 deletions,
validate still passing). Install a sha256-pinned pandoc 3.10 static binary in
CI so regeneration is byte-reproducible and the drift check fires only on real
spec changes. Document the required version in build-reference.sh and AGENTS.
---
 .github/workflows/ci.yml   | 13 +++++++++++--
 AGENTS.md                  |  6 +++++-
 CHANGELOG.md               |  8 ++++++++
 scripts/build-reference.sh |  7 +++++++
 4 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d5ee948..cc5ab3c 100644
--- a/.github/workflows/ci.yml
+++ b/.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
diff --git a/AGENTS.md b/AGENTS.md
index dae935f..941b173 100644
--- a/AGENTS.md
+++ b/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
 ```
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 69ba5f3..8f23491 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/scripts/build-reference.sh b/scripts/build-reference.sh
index 4580687..845d768 100755
--- a/scripts/build-reference.sh
+++ b/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"