From 140024ea372bc8c28874e21b2708e1a5257c524f Mon Sep 17 00:00:00 2001
From: Hiroshi Shinaoka <h.shinaoka@gmail.com>
Date: Sat, 20 Jun 2026 07:11:19 +0900
Subject: [PATCH] rules: add source-blind build-test variant + validate-rules
 CI gate

Extends the Documentation Audits rule with a build/compile-check variant (write
a minimal integration from docs only, then compile it). Adds a minimal
validate-rules workflow that checks rules/index.md links resolve - the required
status check that gates auto-merge on this repo.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .github/workflows/validate.yml | 37 ++++++++++++++++++++++++++++++++++
 rules/common/docs-and-tests.md |  7 +++++++
 2 files changed, 44 insertions(+)
 create mode 100644 .github/workflows/validate.yml

diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
new file mode 100644
index 0000000..49bc86d
--- /dev/null
+++ b/.github/workflows/validate.yml
@@ -0,0 +1,37 @@
+name: Validate rules
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate-rules:
+    name: validate-rules
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check rules/index.md links resolve
+        run: |
+          python3 - <<'PY'
+          import re, pathlib, sys
+
+          rules = pathlib.Path("rules")
+          index = rules / "index.md"
+          text = index.read_text(encoding="utf-8")
+          links = re.findall(r"\]\(([^)#]+\.md)[^)]*\)", text)
+          missing = sorted({l for l in links if not (rules / l).exists()})
+          if missing:
+              print("Broken links in rules/index.md:", file=sys.stderr)
+              for m in missing:
+                  print(f"  - {m}", file=sys.stderr)
+              sys.exit(1)
+          print(f"rules/index.md OK: {len(links)} relative links resolve")
+          PY
diff --git a/rules/common/docs-and-tests.md b/rules/common/docs-and-tests.md
index 90fe0c3..5198645 100644
--- a/rules/common/docs-and-tests.md
+++ b/rules/common/docs-and-tests.md
@@ -10,6 +10,13 @@
 - Use the findings to improve the docs or record follow-up issues before
   treating the documentation as complete. After updating user-facing docs, note
   briefly to the user or maintainer when this protocol is worth running.
+- Stronger variant: when the question is whether the docs are enough to *use*
+  the project (not just understand it), run a source-blind build test — have the
+  doc-only agent write a minimal integration from the compiled docs alone, then
+  compile-check that code against the real project. An explain-only audit can
+  pass while a doer is still blocked (for example, missing trait or function
+  signatures, or how to construct core objects); compiling the doc-faithful code
+  surfaces those gaps concretely.
 
 ## Examples