[wshlavacek]

Closes #716.

What the audit turned up

dev/PUNCHLIST.md is not merely gitignored — it is gone. Never committed on any branch, and no copy survives in any working tree here. So the three tracked references did not point somewhere private; they pointed nowhere, and option 1 from the issue ("commit it") had nothing to commit.

That leaves resolving each reference on its own terms, which turns out to be better than restating two rationales in place.

E722: enforced instead of explained

The ignore read bare except: tracked as ROB-4 in dev/PUNCHLIST.md (behavioral fix).

That principle — a catch-all reports a failure, it does not intercept the user asking to stop — had already landed for main()'s post-run cleanup (tests/test_pybnf_cleanup.py). What was left was exactly one site repo-wide: the catch-all around network generation in _initialize_models.

$ uvx ruff@0.15.14 check --select E722 .
pybnf/algorithms/base.py:545:17: E722 Do not use bare `except`
Found 1 error.

A bare except: there caught KeyboardInterrupt, printed "Unknown error occurred during network generation, see log... exiting", and turned Ctrl-C into SystemExit(1) — during what is often the longest unattended stretch of a fit's startup, and therefore exactly when a user interrupts. Narrowed to except Exception:, so an interrupt propagates; the finally still restores the working directory.

With the last site gone, E722 is removed from the ignore list and gated: ruff check . now fails on a new bare except. An enforced rule needs no rationale to audit.

F841: the rationale now stands on its own

It read unused locals: several are CQ-5 dead code (tracked); common bind-then-assert in tests.

Audited all 20 sites. None is dead code anyone is going to delete:

• 18 in tests — mostly a call made for its effect (usually the exception a pytest.raises block is asserting on) with a name attached to say what was called; one is tests/bngl_files/special_cases/postprocess/bugscript.py, a fixture that must stay broken.
• 2 outside tests — config.py binds an attribute lookup performed for its own sake as a guard on a user-supplied postprocessing script; benchmarks/run_benchmark.py binds the d of the Laloy & Vrugt distance metric so the code reads like the formula quoted beside it.

Ruff's fix in every case is to delete the binding, which loses the intent — so the rule stays off repo-wide, and the comment now says why in terms a reviewer can check against the tree.

The slow tier's pass criterion

tests/README_integration.md defined the tier as the check "for the algorithm patches in dev/PUNCHLIST.md", which made a normative testing requirement unresolvable. It now applies to any change to a sampler or optimizer, and states what a contributor has to claim (efficiency/diagnostic → moments unchanged; correctness → moments move toward analytical truth).

Swept in: the uv.lock contradiction

The issue flagged this as the same defect class, and it is — a tracked file describing a state of the repo that is not true, in both directions:

• CONTRIBUTING.md asserted "the project uses a populated uv.lock" — but .gitignore excludes it, so a clone has no lock at all.
• .pre-commit-config.yaml claimed a sync would fail because the lock "isn't fully resolved in this repo".

Both checked. A fresh resolve from pyproject.toml succeeds (Resolved 87 packages in 1.22s) and uv lock --check on the working copy is clean, so neither claim held. Each comment now describes what the repository actually does; --no-sync stays, for the reason that actually applies to a push hook.

Tests

TestNetworkGenerationErrorHandling pins the narrowed handler:

• a KeyboardInterrupt propagates — mutation-distinguishing, since with the bare clause this raised SystemExit(1) with the "Unknown error" message;
• an ordinary exception is still reported and still exits 1, so the narrowing does not cost the reporting it narrows;
• the working directory is restored either way.

Full suite green locally with BNGPATH set: 5195 passed, 25 skipped, 0 failed. uvx ruff@0.15.14 check . passes with E722 now enforced.

Note on one reference left alone

tests/test_pybnf_cleanup.py still says "ROB-4" three times, and that is deliberate: its module docstring states the principle in full in the same breath, so the tag there is a label rather than a pointer. The new comments in this PR name the principle and the covering test file instead of the tag.