ci: add docstring coverage gate via interrogate

.github/workflows/ci.yml

@@ -56,6 +56,32 @@ jobs:
       - run: uv run mypy src/
         working-directory: ${{ matrix.dir }}
 
+  docstrings:
+    # Public API surface in src/ must carry docstrings. interrogate
+    # threshold is configured per-package in [tool.interrogate]
+    # in each pyproject.toml; raise the floor over time as gaps
+    # are filled.
+    name: Docstring Coverage (${{ matrix.name }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: resq-mcp
+            dir: packages/resq-mcp
+          - name: resq-dsa
+            dir: packages/resq-dsa
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - run: uvx interrogate --config pyproject.toml src/
+        working-directory: ${{ matrix.dir }}
+
   test:
     name: Test (${{ matrix.name }} / ${{ matrix.python-version }})
     needs: [lint, typecheck]

packages/resq-dsa/pyproject.toml

@@ -45,6 +45,23 @@ select = ["E", "W", "F", "I", "B", "C4", "UP", "SIM", "RUF"]
 strict = true
 python_version = "3.11"
 
+[tool.interrogate]
+# Current coverage is 100% under the exclusions below (the 2
+# missing in trie.py are private helpers ignored by ignore-private).
+# Threshold set at 90% to leave headroom for refactors that
+# temporarily expose a new symbol before its docstring lands.
+fail-under = 90
+ignore-init-module = true
+ignore-init-method = true
+ignore-magic = true
+ignore-private = true
+ignore-property-decorators = true
+ignore-nested-functions = true
+exclude = ["tests", "build", "dist"]
+verbose = 1
+quiet = false
+color = true
+
 [tool.semantic_release]
 version_toml = ["pyproject.toml:project.version"]
 branch = "main"

packages/resq-mcp/pyproject.toml

@@ -123,6 +123,24 @@ exclude_lines = [
   "if __name__ == .__main__.:",
 ]
 
+[tool.interrogate]
+# Initial fail threshold set just below current measured coverage
+# under the exclusions below (81%) so the gate locks in today's level
+# and forces ratcheting up as docstrings are added. Concentration of
+# misses is in core/telemetry.py (OpenTelemetry helpers); document
+# those next and raise this number.
+fail-under = 75
+ignore-init-module = true
+ignore-init-method = true
+ignore-magic = true
+ignore-private = true
+ignore-property-decorators = true
+ignore-nested-functions = true
+exclude = ["tests", "build", "dist"]
+verbose = 1
+quiet = false
+color = true
+
 [tool.semantic_release]
 version_toml = ["pyproject.toml:project.version"]
 branch = "main"