Enforce docstring coverage in lint gates

Makefile

@@ -18,6 +18,7 @@ check-fmt: ## Verify template test formatting
 
 lint: ## Run template test lint checks
 	$(UV) ruff check tests/
+	$(UV) --with interrogate interrogate --fail-under 100 tests/
 
 typecheck: ## Run template test type checks
 	$(UV) --with pytest --with pytest-copier --with pyyaml --with syrupy --with make-parser ty check tests/

template/AGENTS.md.jinja

@@ -81,8 +81,9 @@
     - `make check-fmt` runs Ruff formatting checks with
       `ruff format --check $(PYTHON_TARGETS)`.
     - `make lint` runs `make lint-python`; `make lint-python` runs
-      `ruff check $(PYTHON_TARGETS)` and the PyPy-backed Pylint runner against
-      `$(PYLINT_TARGETS)`.
+      `ruff check $(PYTHON_TARGETS)`, enforces 100% docstring coverage with
+      `interrogate --fail-under 100 {{ package_name }}`, and runs the
+      PyPy-backed Pylint runner against `$(PYLINT_TARGETS)`.
     - `make typecheck` runs `ty check $(PYTHON_TARGETS)`.
     - `make test` runs `pytest -v -n $(PYTEST_XDIST_WORKERS)` and honours
       `WITH_ACT=1` through `RUN_ACT_VALIDATION=1`.

template/Makefile.jinja

@@ -136,6 +136,7 @@ lint: lint-python{% if use_rust %} lint-rust{% endif %} ## Run linters
 
 lint-python: build ## Run Python linters
 	$(UV_ENV) $(UV) run ruff check $(PYTHON_TARGETS)
+	$(UV_ENV) $(UV) run interrogate --fail-under 100 {{ package_name }}
 	$(PYLINT) $(PYLINT_TARGETS)
 {% if use_rust %}
 

template/pyproject.toml.jinja

@@ -10,6 +10,7 @@ dependencies = []
 [dependency-groups]
 dev = [
     "pytest",
+    "interrogate",
     "pip-audit",
     "ruff",
     "pyright",

template/{% if use_rust %}rust_extension{% endif %}/Cargo.toml.jinja

@@ -8,7 +8,7 @@ name = "_{{ package_name }}_rs"
 crate-type = ["cdylib", "rlib"]
 
 [dependencies]
-pyo3 = { version = "0.28.3", features = ["extension-module"] }
+pyo3 = { version = "0.29.0", features = ["extension-module"] }
 
 [lints.clippy]
 pedantic = { level = "warn", priority = -1 }

tests/helpers/agents_contracts.py

@@ -98,7 +98,9 @@ def _assert_documented_command_flags(
         ],
         "lint-python": [
             ("AGENTS.md", "ruff check $(PYTHON_TARGETS)"),
+            ("AGENTS.md", f"interrogate --fail-under 100 {package_name}"),
             ("Makefile", f"ruff check {python_targets}"),
+            ("Makefile", f"interrogate --fail-under 100 {package_name}"),
         ],
         "typecheck": [
             ("AGENTS.md", "ty check $(PYTHON_TARGETS)"),

tests/helpers/makefile_contracts.py

@@ -56,6 +56,7 @@ def _parse_makefile_rules(makefile: str) -> dict[str, list[str]]:
     }
 
     def normalise_target(match: re.Match[str]) -> str:
+        """Replace hyphenated target names with parser-compatible aliases."""
         target = match.group(1)
         return normalised_targets.get(target, target) + ":"
 
@@ -104,6 +105,9 @@ def _assert_makefile_contracts(*, makefile: str, use_rust: bool) -> None:
     assert "$(UV_ENV) $(UV) run pip-audit" in makefile, (
         "expected generated audit target to run pip-audit"
     )
+    assert "$(UV_ENV) $(UV) run interrogate --fail-under 100" in makefile, (
+        "expected generated lint target to enforce docstring coverage"
+    )
     if use_rust:
         assert "TEST_CMD :=" in makefile, (
             "expected Rust variant to select nextest or cargo test"

tests/helpers/pyproject_contracts.py

@@ -32,7 +32,16 @@ def _assert_pyproject_contracts(
     assert isinstance(dev_dependencies, list), (
         "expected generated pyproject.toml to include a dev dependency group"
     )
-    for dependency in ["pytest", "pip-audit", "ruff", "pyright", "ty", "pytest-xdist"]:
+    for dependency in [
+        "pytest",
+        "interrogate",
+        "pip-audit",
+        "ruff",
+        "pyright",
+        "ty",
+        "pytest-timeout",
+        "pytest-xdist",
+    ]:
         assert dependency in dev_dependencies, (
             f"expected generated dev dependencies to include {dependency}"
         )

tests/test_github_actions_integration.py

@@ -173,6 +173,7 @@ def test_run_act_forwards_only_explicit_act_github_token(
     captured_command: list[str] = []
 
     def fake_run(command: list[str], **_: Any) -> subprocess.CompletedProcess[str]:
+        """Capture the act subprocess command without executing it."""
         captured_command.extend(command)
         return subprocess.CompletedProcess(command, 0, "stdout", "stderr")
 

tests/test_helpers.py

@@ -456,6 +456,9 @@ def test_parent_makefile_test_target_uses_requisite_pytest_command() -> None:
     assert "$(UV) ruff check tests/" in makefile, (
         "expected parent Makefile lint target to run Ruff checks"
     )
+    assert "$(UV) --with interrogate interrogate --fail-under 100 tests/" in makefile, (
+        "expected parent Makefile lint target to enforce docstring coverage"
+    )
     assert "typecheck: ## Run template test type checks" in makefile, (
         "expected parent Makefile to expose a documented typecheck target"
     )

tests/utilities.py

@@ -39,6 +39,7 @@
 def _resolved_socket_from_docker_host(
     docker_host: str, allowed_dirs: tuple[Path, ...]
 ) -> Path | None:
+    """Return a trusted Unix socket path parsed from ``DOCKER_HOST``."""
     parsed = urlparse(docker_host)
     if parsed.scheme != "unix" or parsed.netloc or not parsed.path:
         return None
@@ -54,6 +55,7 @@ def _resolved_socket_from_docker_host(
 
 
 def _user_podman_socket() -> Path | None:
+    """Return the current user's Podman socket when it exists under runtime dir."""
     socket_path = Path(f"/run/user/{os.getuid()}/podman/podman.sock")
     if not socket_path.exists():
         return None