Structure lint validates git-tracked content, not the raw filesystem

Untracked local scratch (.pytest_cache/, in-progress downloads) is out of
scope — the layout contract is about what gets committed. Falls back to a
filesystem walk outside a git checkout (freshly spawned template). The
stale !lensing_wiki/log.md gitignore exception follows the wiki/ move.

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

Author: 2 people

.gitignore

@@ -34,6 +34,7 @@ desktop.ini
 *.swp
 *~
 __pycache__/
+.pytest_cache/
 *.pyc
 
 # LaTeX build artefacts
@@ -48,4 +49,4 @@ __pycache__/
 *.toc
 
 # Exception — the wiki's own log.md is text and must be tracked
-!lensing_wiki/log.md
+!wiki/*/log.md

scripts/validate_structure.py

@@ -10,6 +10,7 @@
 from __future__ import annotations
 
 import argparse
+import subprocess
 import sys
 from pathlib import Path
 
@@ -41,6 +42,26 @@
 
 
 def iter_repo_files(root: Path):
+    """Yield the repo's content files — git-tracked when git is available.
+
+    Validating `git ls-files` (not the raw filesystem) keeps untracked local
+    scratch — caches, in-progress downloads — out of scope: the contract is
+    about what gets committed. Outside a git checkout (e.g. a freshly spawned
+    template before `git init`) fall back to walking the tree.
+    """
+    try:
+        tracked = subprocess.run(
+            ["git", "-C", str(root), "ls-files", "-z"],
+            capture_output=True,
+            check=True,
+        ).stdout.decode()
+        for rel in sorted(filter(None, tracked.split("\0"))):
+            path = root / rel
+            if path.is_file():
+                yield path
+        return
+    except (OSError, subprocess.CalledProcessError):
+        pass
     for path in sorted(root.rglob("*")):
         if ".git" in path.relative_to(root).parts:
             continue
@@ -50,11 +71,12 @@ def iter_repo_files(root: Path):
 
 def validate_structure(root: Path) -> list[str]:
     errors: list[str] = []
+    top_level = {p.relative_to(root).parts[0] for p in iter_repo_files(root)}
 
     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 name == ".git" or name not in top_level:
+            continue  # untracked local scratch (caches, downloads) is out of scope
         if entry.is_dir():
             if name not in ALLOWED_TOP_DIRS:
                 errors.append(

tests/test_validate_structure.py

@@ -22,6 +22,7 @@ def test_clean_layout_passes(tmp_path):
 def test_unexpected_top_level_entries_fail(tmp_path):
     root = _minimal_repo(tmp_path)
     (root / "DarkMatterModels").mkdir()
+    (root / "DarkMatterModels" / "Navarro1996").write_text("", encoding="utf-8")
     (root / "euclid.sty").write_text("", encoding="utf-8")
     errors = validate_structure(root)
     assert any("DarkMatterModels" in e for e in errors)