From 05928ca52d9abef8aef47602bca294af44dbd1f5 Mon Sep 17 00:00:00 2001
From: Kin Lane <kinlane@gmail.com>
Date: Fri, 7 Aug 2026 08:32:44 -0400
Subject: [PATCH] Build CI the way GitHub Pages does, so CI predicts the deploy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI pins jekyll ~> 4.4 while Pages runs github-pages 232 (Jekyll 3.10),
so CI cannot see the class of failure roadmap.md already warns about in
a comment: Jekyll 3.10's where_exp takes one comparison and then demands
end-of-string, and `and` / `or` inside it is Jekyll 4 only.

spotlight-spec proved the cost of that gap — the same mistake there kept
pages-build-deployment red for 20+ commits with CI green throughout and
the site serving a week-old build.

Add a second job that builds against .github/Gemfile.pages, deliberately
unpinned. Nothing here needs fixing first: every template in this repo
already parses under Jekyll 3.10.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .github/Gemfile.pages    | 15 +++++++++++++++
 .github/workflows/ci.yml | 20 ++++++++++++++++++++
 .gitignore               |  1 +
 3 files changed, 36 insertions(+)
 create mode 100644 .github/Gemfile.pages

diff --git a/.github/Gemfile.pages b/.github/Gemfile.pages
new file mode 100644
index 0000000..b6bf6e4
--- /dev/null
+++ b/.github/Gemfile.pages
@@ -0,0 +1,15 @@
+# The Gemfile GitHub Pages actually builds with — not the one in the repo root.
+#
+# `pages-build-deployment` ignores our Gemfile and runs the `github-pages` gem
+# (currently 232, which pins Jekyll 3.10). Jekyll 3.10 forgives less Liquid than
+# the Jekyll 4 we develop against: `where_exp` takes exactly one comparison and
+# then demands end-of-string, so `and` / `or` inside the expression — a Jekyll 4
+# feature — parses locally and dies on deploy. roadmap.md already carries a
+# comment about that trap; this file is what makes CI catch the next one.
+#
+# CI builds against this file so it predicts the deploy. Do not pin a version
+# here: tracking whatever `github-pages` currently resolves to is the point.
+
+source "https://rubygems.org"
+
+gem "github-pages", group: :jekyll_plugins
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d155990..68e8727 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -3,8 +3,11 @@ on:
   pull_request:
   push:
     branches: [main]
+
 jobs:
+  # The Jekyll we develop against. Fast, and matches a local `jekyll serve`.
   build:
+    name: Jekyll 4 (what we develop on)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -13,3 +16,20 @@ jobs:
           ruby-version: '3.2'
           bundler-cache: true
       - run: bundle exec jekyll build
+
+  # The build that actually predicts the deploy. GitHub Pages ignores the root
+  # Gemfile and runs the `github-pages` gem (Jekyll 3.10), which accepts less
+  # Liquid than Jekyll 4 — see .github/Gemfile.pages. Without this job, CI stays
+  # green while pages-build-deployment fails and the site silently serves stale.
+  pages-parity:
+    name: GitHub Pages (what actually deploys)
+    runs-on: ubuntu-latest
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/.github/Gemfile.pages
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+      - run: bundle exec jekyll build
diff --git a/.gitignore b/.gitignore
index 119286a..ac51552 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,4 +4,5 @@ _site/
 vendor/
 .bundle/
 Gemfile.lock
+Gemfile.pages.lock
 .DS_Store