Include hidden files in Pages artifact; smoke-test deploy

The first production deploy shipped 230 PDS records and all link tags
but served 404 for /.well-known/site.standard.publication:
actions/upload-pages-artifact excludes dot-prefixed entries from its
tar by default, so the file was built, green through every gate, and
silently dropped at packaging. No _site-level check can catch what
the packaging step discards.

Changes:
- upload-pages-artifact: include-hidden-files: true.
- deploy job: post-deploy smoke test curls the live .well-known URL
  and compares it to the URI in _config.yml, retrying for CDN
  propagation; checkout added for config access.
- validate --site-dir also verifies _site/.well-known/... exists with
  byte-exact content (closes the adjacent generator-regression gap;
  the artifact gap is only provable post-deploy).
- bluesky.md Phase 5 documents the incident and the three guards.

Author: agude

.github/workflows/jekyll.yml

@@ -174,9 +174,15 @@ jobs:
           bundle exec ruby _bin/check_links.rb
 
       - name: Upload artifact
-        # Only upload if we are on main (where deployment happens)
+        # Only upload if we are on main (where deployment happens).
+        # include-hidden-files is required: the action's tar excludes
+        # dot-prefixed entries by default, which silently dropped
+        # .well-known/site.standard.publication from the first deploy
+        # while every _site-level gate stayed green.
         if: github.ref == 'refs/heads/main'
         uses: actions/upload-pages-artifact@v5
+        with:
+          include-hidden-files: true
 
   # Deployment job
   deploy:
@@ -191,6 +197,24 @@ jobs:
     # This matches the condition above, ensuring we only try to deploy if we uploaded
     if: github.ref == 'refs/heads/main'
     steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v5
+
+      # Artifact-side proof that dot-path files actually deployed; the
+      # build gates can only see _site/, not what the packaging step kept.
+      - name: Smoke-test deployed .well-known
+        run: |
+          expected=$(grep -A2 '^standard_site:' _config.yml | grep publication_uri | sed 's/.*"\(at:[^"]*\)".*/\1/')
+          echo "Expecting: $expected"
+          for i in 1 2 3 4 5; do
+            got=$(curl -fsS "${{ steps.deployment.outputs.page_url }}.well-known/site.standard.publication" || true)
+            [ "$got" = "$expected" ] && echo "OK" && exit 0
+            echo "attempt $i: got '$got'; retrying in 15s (CDN propagation)"
+            sleep 15
+          done
+          echo "ERROR: deployed .well-known does not serve the publication URI"
+          exit 1

_scripts/atproto/publish.py

@@ -732,6 +732,7 @@ def validate_documents(
     posts_dir: Path,
     books_dir: Path | None = None,
     site_dir: Path | None = None,
+    expected_publication_uri: str = "",
 ) -> bool:
     """
     Validate all posts (and books) for AT Protocol compatibility.
@@ -777,6 +778,24 @@ def validate_documents(
             print(f"ERROR: {msg}", file=sys.stderr)
             error_count += 1
 
+        # The built site must carry the verification file with the exact
+        # configured URI (no trailing newline — verifiers compare exactly).
+        if expected_publication_uri:
+            wk = site_dir / ".well-known" / "site.standard.publication"
+            if not wk.is_file():
+                print(
+                    f"ERROR: built site is missing {wk}",
+                    file=sys.stderr,
+                )
+                error_count += 1
+            elif wk.read_text(encoding="utf-8") != expected_publication_uri:
+                print(
+                    f"ERROR: {wk} content does not match "
+                    "standard_site.publication_uri",
+                    file=sys.stderr,
+                )
+                error_count += 1
+
     return error_count == 0
 
 
@@ -921,10 +940,14 @@ def _dispatch(argv: list[str] | None = None) -> None:
 
     args = parser.parse_args(argv)
 
-    # validate needs no credentials or config — dispatch before either check.
+    # validate needs no credentials or network; it reads only local files
+    # (including _config.yml for the expected publication URI).
     if args.cmd == "validate":
         ok = validate_documents(
-            args.posts_dir, books_dir=args.books_dir, site_dir=args.site_dir
+            args.posts_dir,
+            books_dir=args.books_dir,
+            site_dir=args.site_dir,
+            expected_publication_uri=get_publication_uri(load_config()),
         )
         if not ok:
             sys.exit(1)

_scripts/tests/test_atproto_publish.py

@@ -1641,3 +1641,51 @@ def test_update_without_cid_refuses(self, tmp_path: Path) -> None:
         with pytest.raises(publish.PublishError) as exc_info:
             sync_documents(client, tmp_path, tmp_path / "out.json", PUB_URI, TEST_CONFIG)
         assert "non-atomic" in str(exc_info.value)
+
+# ---------------------------------------------------------------------------
+# Well-known file check in validate --site-dir
+# ---------------------------------------------------------------------------
+
+
+class TestWellKnownInSite:
+    def _site(self, tmp_path: Path) -> tuple[Path, Path]:
+        posts = tmp_path / "posts"
+        posts.mkdir()
+        site = tmp_path / "_site"
+        (site / "blog").mkdir(parents=True)
+        (site / "books").mkdir(parents=True)
+        return posts, site
+
+    def test_missing_well_known_fails(self, tmp_path: Path, capsys) -> None:
+        posts, site = self._site(tmp_path)
+        ok = validate_documents(posts, site_dir=site, expected_publication_uri=PUB_URI)
+        assert ok is False
+        assert "missing" in capsys.readouterr().err
+
+    def test_wrong_content_fails(self, tmp_path: Path, capsys) -> None:
+        posts, site = self._site(tmp_path)
+        wk = site / ".well-known"
+        wk.mkdir()
+        (wk / "site.standard.publication").write_text("at://did:plc:wrong/x/y")
+        ok = validate_documents(posts, site_dir=site, expected_publication_uri=PUB_URI)
+        assert ok is False
+        assert "does not match" in capsys.readouterr().err
+
+    def test_trailing_newline_fails(self, tmp_path: Path) -> None:
+        # Verifiers compare exactly; a newline is a mismatch.
+        posts, site = self._site(tmp_path)
+        wk = site / ".well-known"
+        wk.mkdir()
+        (wk / "site.standard.publication").write_text(PUB_URI + "\n")
+        assert validate_documents(posts, site_dir=site, expected_publication_uri=PUB_URI) is False
+
+    def test_exact_content_passes(self, tmp_path: Path) -> None:
+        posts, site = self._site(tmp_path)
+        wk = site / ".well-known"
+        wk.mkdir()
+        (wk / "site.standard.publication").write_text(PUB_URI)
+        assert validate_documents(posts, site_dir=site, expected_publication_uri=PUB_URI) is True
+
+    def test_no_expected_uri_skips_check(self, tmp_path: Path) -> None:
+        posts, site = self._site(tmp_path)
+        assert validate_documents(posts, site_dir=site) is True

bluesky.md

@@ -389,11 +389,15 @@ exercised the unconfigured code. Before merging `standard-site-config`:
 
 1. After the first `main` deploy:
    `curl https://alexgude.com/.well-known/site.standard.publication`
-   → exactly the publication AT-URI. This is also the first proof that
-   GitHub Pages serves this repo's `.well-known/` path at all — Pages
-   generally does, but it has never been verified here; if it 404s
-   while `_site/` contains the file, that is a Pages serving issue,
-   not a build issue.
+   → exactly the publication AT-URI. **This check caught a real bug on
+   the first deploy**: `actions/upload-pages-artifact` excludes
+   dot-prefixed entries from its tar by default, so `.well-known` was
+   built and green through every gate, then silently dropped at
+   packaging. Fixed with `include-hidden-files: true` on the upload
+   step; a post-deploy smoke test in the deploy job now curls the live
+   URL and compares content (with retries for CDN propagation), and
+   `validate --site-dir` checks the file exists in `_site/` with exact
+   content.
 2. `curl -s https://alexgude.com/blog/<recent-slug>/ | grep site.standard`
    → both link tags present.
 3. Run the ecosystem validator at <https://site-validator.fly.dev>