rules: add source-blind build-test variant to documentation audits

.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

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