Add a structure lint: two content homes, no loose bibs, no committed papers

scripts/validate_structure.py enforces the layout contract that would have
prevented the pre-cleanup state: a top-level allowlist, .bib only under
bibliography/, and no paper artifacts (PDF suffix or PDF magic bytes, so
extensionless ADS downloads are caught too). Wired into make validate and
a minimal GitHub Actions workflow alongside the existing citation
validator; the write contract is documented in AGENTS.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: 2 people

.github/workflows/validate.yml

@@ -0,0 +1,18 @@
+name: validate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install pytest
+      - run: make validate
+      - run: make test

Makefile

@@ -1,4 +1,12 @@
-.PHONY: validate-literature-citations
+.PHONY: validate validate-literature-citations validate-structure test
+
+validate: validate-literature-citations validate-structure
 
 validate-literature-citations:
 	python scripts/validate_literature_citations.py
+
+validate-structure:
+	python scripts/validate_structure.py
+
+test:
+	python -m pytest tests/ -q

scripts/validate_structure.py

@@ -0,0 +1,103 @@
+"""Validate the PyAutoMemory repository layout.
+
+The repo has exactly two content homes — `wiki/` (sub-wikis) and
+`bibliography/` (canonical BibTeX) — plus a small allowlisted set of root
+files and tooling folders. This lint fails on the historical failure modes:
+loose `.bib` files outside `bibliography/`, committed papers (PDF/HTML blobs,
+with or without a file extension), and unrecognised top-level entries.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+ALLOWED_TOP_DIRS = {
+    ".git",
+    ".github",
+    "bibliography",
+    "scripts",
+    "tests",
+    "wiki",
+}
+ALLOWED_TOP_FILES = {
+    ".gitignore",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "Makefile",
+    "README.md",
+    "index.md",
+    "logo.png",
+    "reading-queue.md",
+}
+BANNED_SUFFIXES = {".pdf", ".htm", ".html"}
+BINARY_MAGIC = (b"%PDF-",)
+BINARY_EXEMPT = {"logo.png"}
+
+
+def iter_repo_files(root: Path):
+    for path in sorted(root.rglob("*")):
+        if ".git" in path.relative_to(root).parts:
+            continue
+        if path.is_file():
+            yield path
+
+
+def validate_structure(root: Path) -> list[str]:
+    errors: list[str] = []
+
+    for entry in sorted(root.iterdir()):
+        name = entry.name
+        if name == ".git":  # a directory in a normal checkout, a file in a worktree
+            continue
+        if entry.is_dir():
+            if name not in ALLOWED_TOP_DIRS:
+                errors.append(
+                    f"unexpected top-level directory: {name}/ "
+                    "(content belongs under wiki/ or bibliography/)"
+                )
+        elif name not in ALLOWED_TOP_FILES:
+            errors.append(
+                f"unexpected top-level file: {name} "
+                "(allowlist lives in scripts/validate_structure.py)"
+            )
+
+    for path in iter_repo_files(root):
+        rel = path.relative_to(root)
+        if path.suffix == ".bib" and rel.parts[0] != "bibliography":
+            errors.append(f"loose .bib file outside bibliography/: {rel}")
+        if path.suffix.lower() in BANNED_SUFFIXES:
+            errors.append(f"committed paper artifact (source PDFs live off-repo): {rel}")
+        elif rel.name not in BINARY_EXEMPT:
+            try:
+                head = path.open("rb").read(8)
+            except OSError:
+                head = b""
+            if head.startswith(BINARY_MAGIC):
+                errors.append(f"committed PDF content (source PDFs live off-repo): {rel}")
+
+    return errors
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=ROOT)
+    args = parser.parse_args(argv)
+
+    errors = validate_structure(args.root.resolve())
+    for error in errors:
+        print(f"ERROR: {error}")
+    if errors:
+        print(f"Repository structure is invalid ({len(errors)} problem(s)).")
+        return 1
+    print("Repository structure is valid.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_validate_structure.py

@@ -0,0 +1,48 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from scripts.validate_structure import validate_structure
+
+
+def _minimal_repo(tmp_path: Path) -> Path:
+    (tmp_path / "wiki" / "example" / "sources").mkdir(parents=True)
+    (tmp_path / "bibliography").mkdir()
+    (tmp_path / "bibliography" / "pyautomemory.bib").write_text("", encoding="utf-8")
+    (tmp_path / "README.md").write_text("# readme\n", encoding="utf-8")
+    return tmp_path
+
+
+def test_clean_layout_passes(tmp_path):
+    root = _minimal_repo(tmp_path)
+    assert validate_structure(root) == []
+
+
+def test_unexpected_top_level_entries_fail(tmp_path):
+    root = _minimal_repo(tmp_path)
+    (root / "DarkMatterModels").mkdir()
+    (root / "euclid.sty").write_text("", encoding="utf-8")
+    errors = validate_structure(root)
+    assert any("DarkMatterModels" in e for e in errors)
+    assert any("euclid.sty" in e for e in errors)
+
+
+def test_loose_bib_outside_bibliography_fails(tmp_path):
+    root = _minimal_repo(tmp_path)
+    (root / "wiki" / "example" / "library.bib").write_text("", encoding="utf-8")
+    errors = validate_structure(root)
+    assert any("loose .bib" in e for e in errors)
+
+
+def test_committed_pdf_content_fails_even_without_extension(tmp_path):
+    root = _minimal_repo(tmp_path)
+    (root / "wiki" / "example" / "Hubble1926.321H").write_bytes(b"%PDF-1.5 fake")
+    (root / "wiki" / "example" / "paper.pdf").write_bytes(b"%PDF-1.4 fake")
+    errors = validate_structure(root)
+    assert sum("off-repo" in e for e in errors) == 2
+
+
+def test_actual_repository_layout_is_valid():
+    repo_root = Path(__file__).resolve().parents[1]
+    assert validate_structure(repo_root) == []