fix(lint): fail the prose gate cleanly on a missing root, and name th…

…e blank-line blind spot A renamed root now prints one line and exits 1 instead of a traceback. The own_comment_runs docstring and CLAUDE.md now state that two blank lines at module scope split a run. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
uipreliga · Sep 16, 2026 · Sep 15, 2026 · Sep 15, 2026 · Sep 15, 2026 · Sep 15, 2026
commit d20d40e603fbdf5775d2968049d120c268c03410
@@ -310,8 +310,8 @@ bandit, pre-commit, mcp
   it correctly. Why the design is this shape belongs in `.claude/notes/`; what it used to
   be belongs in git. `make docs-budget` applies three self-adjusting rules to `src/` and
   `tests/`: no own-line comment RUN may exceed 8 lines (a run reads through one blank line,
-  so splitting a paragraph does not duck it), a file's own-line comments may not exceed
-  `MAX(20, 0.15 × its length)` in total, and no docstring may exceed 150 words of PROSE (an
+  so a paragraph split on one blank line does not duck it), a file's own-line comments may
+  not exceed `MAX(20, 0.15 × its length)` in total, and no docstring may exceed 150 words of PROSE (an
   `Args:`/`Returns:`/`Raises:` block is structure, not prose; an `@abstractmethod` is exempt
   because its docstring IS the interface contract). The run cap governs the SHAPE of any one
   comment — put the paragraph in `.claude/notes/` behind a `Rationale:` pointer — and the

@@ -405,6 +405,9 @@ def own_comment_runs(source: str) -> list[tuple[int, int]]:
     does not read as several short comments. Code between two comments always ends
     the run. A trailing ``# noqa`` never starts one: it is a directive, not
     commentary.
+
+    Blind spot: at module scope ruff format keeps two blank lines, so a paragraph split
+    on two blank lines there reads as two runs.
     """
     lines = source.split("\n")
     try:
@@ -583,7 +586,14 @@ def assert_code_unchanged(repo_root: Path, ref: str) -> list[str]:
 
 def main(argv: list[str]) -> int:
     repo_root = Path(__file__).resolve().parents[2]
+    try:
+        return _run(repo_root, argv)
+    except FileNotFoundError as error:
+        print(error, file=sys.stderr)
+        return 1
+
 
+def _run(repo_root: Path, argv: list[str]) -> int:
     if argv[:1] == ["--assert-code-unchanged"]:
         if len(argv) != 2:
             print("usage: --assert-code-unchanged <git-ref>", file=sys.stderr)

@@ -489,6 +489,13 @@ def test_a_missing_root_raises(self, tmp_path: Path, monkeypatch: pytest.MonkeyP
         with pytest.raises(FileNotFoundError, match="nope"):
             prose_budget.measure(tmp_path)
 
+    def test_a_missing_root_fails_the_gate_without_a_traceback(
+        self, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        monkeypatch.setattr(prose_budget, "_ROOTS", (Path("nope"),))
+        assert prose_budget.main([]) == 1
+        assert capsys.readouterr().err == "prose budget root does not exist: nope\n"
+
     def test_two_roots_are_both_measured(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
         root = _write(tmp_path, {"src/coder_eval/a.py": _ESSAY, "tests/b.py": _ESSAY})
         monkeypatch.setattr(prose_budget, "_ROOTS", (Path("src/coder_eval"), Path("tests")))