verify(P3): docs build CI — 4 layers green

Structural: YAML schema valid; jobs go-test + docs-build; docs-build
needs go-test (G-016 OK). Behavioral: local mkdocs build succeeds (site/
produced); go test ./... green. Security: go.mod unchanged (G-006 intact);
Python deps isolated to docs-build job. Quality: .gitignore covers site/.
NFR purity: zero commit SUBJECTS starting with feat: (grep -E '^feat:'
exit 1 on subject-only check). NOTE: git log --grep matches message BODIES
too (prose mentions 'feat:'); the P4 audit gate uses subject-only check
(git log --format='%s' | grep -E '^feat:').

---ci---
project: oy
phase: 3
milestone: v0.4
status: verify
tag_base: v0.3.x
milestone_type: nfr
reqs: [REQ-032]
---/ci---

.ciagent/CHECKPOINT.json

@@ -1,5 +1,5 @@
 {
-  "phase": 1,
+  "phase": 2,
   "stage": "complete",
   "milestone": "v0.4",
   "milestone_type": "nfr",
@@ -7,8 +7,8 @@
   "phase_role": "execution",
   "project": "oy",
   "attempts": 0,
-  "updated_at": "2026-08-17T23:35:00Z",
-  "phase_release_tag": "v0.3.1",
-  "release_id": 749,
-  "reqs_covered": ["REQ-029", "REQ-030"]
+  "updated_at": "2026-08-17T23:40:00Z",
+  "phase_release_tag": "v0.3.2",
+  "release_id": 750,
+  "reqs_covered": ["REQ-029", "REQ-030", "REQ-031"]
 }

.gitea/workflows/docs-build.yml

@@ -0,0 +1,55 @@
+# OpenYield docs build CI (REQ-032, D-046 forward-reference, D-051, G-016).
+#
+# Runs the lexicon firewall (go test ./...) AND builds the MkDocs Material docs
+# site on every push. The docs-build job DEPENDS on go-test (G-016 binding:
+# firewall-gates-docs-build — a lexicon violation blocks the docs build so no
+# false-green docs artifact is produced from a repo with a firewall failure).
+#
+# Scope (chore, not feat: per D-001 refinement-only filter):
+#   - go-test job: setup Go 1.22, run `go test ./...` (lexicon firewall + all
+#     x/* tests + the v0.4 cross-const test). Zero external Go deps (G-006).
+#   - docs-build job: setup Python, pip install mkdocs + mkdocs-material
+#     (build-only Python deps, ISOLATED to this job — go.mod is NOT modified),
+#     run `mkdocs build` (produces site/), upload site/ as a CI artifact.
+#
+# Out of scope (deferred per D-051): full Gitea Pages publishing. v0.4 ships
+# build + artifact only; a hosting target is not configured.
+#
+# Triggers: on push (all branches) so the firewall + docs build are checked
+# on every change, not just on main.
+
+name: docs-build
+on:
+  push:
+
+jobs:
+  go-test:
+    name: go test ./... (lexicon firewall + all x/* tests)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.22'
+      - name: go test ./...
+        run: go test ./...
+
+  docs-build:
+    name: mkdocs build (docs site artifact)
+    runs-on: ubuntu-latest
+    needs: go-test  # G-016: firewall-gates-docs-build (no false-green docs build)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: install mkdocs + mkdocs-material
+        run: pip install mkdocs mkdocs-material
+      - name: mkdocs build
+        run: mkdocs build
+      - name: upload site/ artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-site
+          path: site/
+          retention-days: 14

.gitignore

@@ -2,3 +2,5 @@
 .env.secrets
 .env.*
 .ciagent/.env.secrets
+# MkDocs build output (REQ-032 CI produces site/ as an artifact; never commit it)
+site/