Maximally strict warnings: broaden the ruff rule set and raise pyright above basic

[cdeust]

Why

warnings_strict — "projects MUST be maximally strict with warnings in the software produced by the project, where practical" — is a MUST at OpenSSF silver and the second criterion blocking the badge (project 13836).

Today the gates block regression but are not strict:

• ruff runs its default rule set (E4, E7, E9, F). A run with --select ALL minus the docstring/annotation/comma/TODO families reports 3,545 findings (measured 2026-07-27, ruff 0.15.20, mcp_server/). Largest classes: PLC0415 import-outside-top-level (405), BLE001 blind-except (349), PLR2004 magic-value comparison (339), E501 line-too-long (263), S110 try-except-pass (68), S608 string-built SQL (39, all identifier-allowlisted — see docs/ASSURANCE-CASE.md §5).
• pyright runs typeCheckingMode: "basic" behind a per-rule ratchet whose committed floors total 568 diagnostics (typecheck-baseline.json).

CI fails on any ruff finding under the current rule set and on any rule above its floor, so nothing accumulates — but a rule that was never enabled cannot fail, and that is what this criterion is about.

Approach

Rule family by rule family, each as its own PR, so review stays reviewable:

1. Enable the mechanical families first (I imports, UP pyupgrade, C4, SIM, PIE, RSE, PERF) — mostly autofixable; land the fix and the config change together.
2. Then the judgement families (B, S, TRY, RET, ARG, PTH, PL*), fixing rather than blanket-ignoring. A rule the project deliberately rejects is disabled in pyproject.toml with a written reason, not left unselected by accident — that distinction is the whole point.
3. Raise pyright from basic toward standard, and keep burning the ratchet floors down (they only come down: see docs/provenance/pyright-remediation-plan.md).

Acceptance criteria

1. [tool.ruff.lint] select is explicit and broad; every excluded family carries a comment stating why it is excluded.
2. ruff check . is clean at the new rule set, and CI still fails on any finding.
3. pyrightconfig.json is above basic, with the ratchet floors at or below their current values — no floor is raised to make the build pass.
4. docs/ASSURANCE-CASE.md § "What this assurance case does NOT claim" drops the strictness caveat.
5. .bestpractices.json flips warnings_strict to Met, citing the configuration rather than a promise.

Blocks: OpenSSF silver (project 13836). Roadmap item 1.

[cdeust]

Scoping measurement, plus the reason this issue is worth more than it looks.

It gates the OpenSSF Silver badge

~/.claude/tools/badge_check.py Cortex --project-id 13836 --levels 0,1 says Silver is 53/55 acceptable = 96%, blocked by exactly two MUST criteria:

REJECTED    test_statement_coverage80: Unmet on a MUST criterion -- this blocks the level
REJECTED    warnings_strict: Unmet on a MUST criterion -- this blocks the level

warnings_strict is this issue; test_statement_coverage80 is #196. Nothing else blocks Silver, and the site has already applied every answer we published (0 answer(s) not applied at both levels), so no re-submission is pending. Silver raises OpenSSF Scorecard's CII-Best-Practices check above its current 5/10.

Current state

There is no [tool.ruff.lint] section in pyproject.toml at all, so ruff runs its default rule set (E4/E7/E9 + F). pyrightconfig.json is "typeCheckingMode": "basic".

What a broad rule set actually costs

ruff check --select E,W,F,I,B,C4,SIM,UP,RET,PTH,RUF,N,ARG,S --statistics on the current tree:

count	rule	note
9570	S101 assert	entirely tests_py/; the standard fix is a per-file-ignore, not 9570 edits
469	E501 line-too-long
318	I001 unsorted-imports	auto-fixable
265 + 149 + 127	ARG001/ARG002/ARG005 unused-argument	the largest genuine class
132	RUF059 unused-unpacked-variable
125 + 123 + 61	RUF001/2/3 ambiguous-unicode	mostly prose punctuation in docstrings
90	S110 try-except-pass	worth reading individually, this hides failures
87	S311 non-cryptographic-random	benchmark sampling, likely per-file-ignore
71	S108 hardcoded-temp-file
64 + 50	PTH118/PTH123 os.path vs pathlib
48	S608 hardcoded-sql-expression	worth reading individually

Excluding S101, roughly 2,500 findings, and a large share are auto-fixable (I001, UP035, RUF100) or resolve to a single per-file-ignore.

Not measured yet: pyright at standard or strict. That number should be taken before committing to a level, since it is the one that could dwarf the ruff work.

Suggested shape

Staged, so each step is reviewable and CI stays green throughout, rather than one 2,500-finding commit:

1. Adopt the auto-fixable rules (I, UP, RUF100) and commit the mechanical fix separately from config.
2. Add per-file-ignores for the test-suite-shaped rules (S101, S311 in benchmarks) with the rationale in the config.
3. Take S110, S608 and the ARG* class as real review, since each can hide a defect. S110 in particular is the same silent-failure shape as the FlashRank incident.
4. Raise pyright only after measuring it.

Acceptance for the badge is narrow: warnings_strict needs the project to be maximally strict and to address the warnings, not merely to enable rules.

[cdeust]

Measured: what each pyright level actually costs (criterion 3)

Measured 2026-07-27 on feat/coverage-80-196 head 6d7f0ca, pyright 1.1.410
(the CI-pinned version), in a CI-equivalent env: .[dev,postgresql,sqlite,codebase]

• flashrank + the otel extra. reportMissingImports lands at 1, matching
  typecheck-baseline.json exactly — the env resolves everything CI's does, so the
  numbers are comparable rather than Unknown-suppressed.

mode	errors	delta vs basic
basic (today)	418	—
standard	418	0
strict	10,231	+9,813

standard is free. Before any fix it cost exactly one diagnostic —
reportIncompatibleVariableOverride at infrastructure/sqlite_store.py:70 — and
that one was a real defect, not a strictness tax (below). With it fixed, standard
and basic report the identical 418.

strict is not reachable: ~9,300 of its 10,231 are the Unknown-type family
(reportUnknownVariableType 2,950, reportUnknownMemberType 2,542,
reportUnknownArgumentType 1,672, reportMissingTypeArgument 1,122,
reportUnknownParameterType 1,061). That is an annotation-coverage project, not a
config flip.

The one diagnostic was a real type-lie

SqliteMemoryStore assigns self._conn = PsycopgCompatConnection(raw), but 9 of the
10 mixins annotated _conn: sqlite3.Connection. Only SqliteGroomingMixin had the
correct type. Every self._conn.… call in those 9 mixins — and every handler reading
store._conn — was therefore checked against the wrong class.

Correcting all 10 to PsycopgCompatConnection is what makes standard cost zero.
It also surfaced a live defect the wrong annotation had been hiding: seven wiki
handlers call store._conn.cursor(), which PsycopgCompatConnection does not
implement, so the wiki pipeline is silently dead on the SQLite backend. Filed as
#206 — out of this issue's blast radius, tracked there per §14.3.

Ratchet safety

scripts/check_pyright_ratchet.py fails only on --blocking rules
(reportOptionalMemberAccess, reportOptionalSubscript); both are at 0 and stay
at 0. No floor is raised — typecheck-baseline.json is untouched, per criterion 3.

Criterion 3 is therefore satisfiable now, independently of the ruff work in
criteria 1–2. Criteria 4–5 stay open until the ruff rule set lands.