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