steam-backlog-enforcer/prompts/TODO-refactor-250-continue.md

Session prompt: continue the 250-line cap refactor

Paste everything below the line into a fresh Claude Code session started in ~/steam-backlog-enforcer.

---

Continue refactor_claude_todo.md: get every file in this repo under 250 lines and take pylint to a clean 10.00, without weakening either gate.

Earlier sessions landed the gate and the three hardest modules. Re-measure before you start — the numbers below were true at commit b5b4b35.

State at handoff

bash scripts/check_file_length.sh --all        # 39 files over the cap
.ci-mirror-venv/bin/python -m pytest steam_backlog_enforcer/tests/ -q
                                               # 1324 pass, 100.00% coverage
~/.cache/pre-commit/repo01lfw04p/py_env-python3/bin/pylint \
    --rcfile=pyproject.toml --jobs=4 steam_backlog_enforcer scripts | tail -2
                                               # 8.69/10

Already done (do not redo):

• The gate is live. scripts/file_length/ is a vendored copy of ~/utils/file_length/, wired as the file-length pre-commit hook. It is excluded from ruff/mypy/pylint and must stay byte-identical to upstream. pre-commit install has been run (it never had been — only pre-push).
• main.py → main/ package; _total_block, _playtime, _mcp split.
• pyproject.toml: max-module-lines = 250.

Decisions already made — do not re-ask

1. All 39 files this campaign, then pylint. Both in scope.
2. Gate stays on: every commit must bring the files it touches under the cap. --no-verify is banned.
3. Coverage must stay at exactly 100%. No pragmas, no omits.
4. Split by responsibility, never mechanically. See below.
5. No private re-export shims. Callers import from the defining module.
6. At the very end: raise pylint --fail-under 8.0 → 10.0 in .pre-commit-config.yaml (a deliberate deviation from prompts/pylint-to-ten.md, which says leave it — a score with no gate regrows exactly like file length does).

How to split (this is the part that goes wrong)

A generic "move these top-level defs to a sibling module" extractor was tried and reverted: it moved functions without the module-level names they referenced, so the result imported fine and only failed when called — ruff check --select F821 found 349 undefined names.

Per file:

1. Read it. Name the 2-4 jobs it does; the existing # ──── section banners usually mark the real seams.
2. Give each job a module whose docstring says why it is separate. Keep the dependency direction one-way, leaf modules (data tables, generic helpers) at the bottom. Pass a dependency as a parameter when that removes a cycle.
3. Never module_x_1.py / module_x_2.py. Extract genuinely reusable helpers under their own name (_pacman.py came out of _total_block this way and is now shared).
4. ruff check --select F821,F401 --no-fix <files> after every extraction. F821 first, then autofix F401 — the reverse order deletes imports the moved code still needs.
5. Repoint the matching test file (below), then commit.

Test files are the real cost

Tests build patch targets as f"{PKG}.{name}", so grepping for the literal module path finds nothing. Once a function moves, it resolves its dependencies from its new module's globals, and a patch aimed at the old module silently stops intercepting.

For each split:

# which module actually defines each patched symbol
.ci-mirror-venv/bin/python - <<'PY'
import importlib, re, pathlib
mods = {m: importlib.import_module(f"steam_backlog_enforcer.{m}") for m in (...)}
src = pathlib.Path("steam_backlog_enforcer/tests/test_X.py").read_text()
for s in sorted(set(re.findall(r'f"\{PKG\}\.(\w+)"', src))):
    print(s, [m for m, mod in mods.items() if s in vars(mod)])
PY

Then split the test file so each output has one correct PKG, and mutation-test at least one assertion per new module — break a line in the production module, confirm the right test fails, restore. A passing test after a split proves nothing on its own. Watch for these forms, which a naive find/replace misses: patch.object(mod, "name"), the multi-line patch.object(\n mod, "name"), and dotted f"{PKG}.subprocess.run".

Two traps that already cost time

• ruff --fix --unsafe-fixes deletes autouse fixture imports (pytest resolves fixtures by name, so they look unused). conftest.py holds them with an explicit __all__ — keep it that way when adding more.
• conftest.py is the filesystem safety net. When a path constant moves to a new module, update the conftest patch target in the same edit, then confirm no test writes outside tmp_path.

Remaining work, highest ROI first

Production (15) — the todo ranks by lines x commits/yr, so start here:

lines	file
555	library_hider.py
553	game_install.py
521	scanning.py
588	_hltb_search.py
523	_stats.py
436	_web_dataset.py
410	_enforce_loop.py
399	store_blocker.py
384	hltb.py
373	_hltb_detail.py
333	_cmd_done.py
298	_whitelist.py
282	_actions.py
281	steam_api.py
253	_scanning_confidence.py

Test files (24), largest first: test_stats.py 1072, test_web_dataset.py 620, test_hltb_detail.py 592, test_store_blocker.py 470, test_library_hider.py 468, test_hltb.py 447, test_scanning.py 444, then 17 more between 255 and 417. Split these to ~200 lines, not 249 — the pylint phase adds a docstring to every test function and would push a 249-line file back over.

Then pylint 8.69 → 10.00 per prompts/pylint-to-ten.md. ~1600 findings, of which 1061 are missing-function-docstring in tests/. Fix duplicate-code (R0801) by extracting shared test helpers, never by adding ignore-imports/ignore-signatures. R0801 is cross-module so it is invisible to the staged-files hook — acceptance is a full-tree run.

Commands

Keep every command under ~10s; nothing over 60s.

# scoped test run for the file you just touched (~0.3s)
python3 -m pytest steam_backlog_enforcer/tests/test_<area>*.py -q --no-cov

# acceptance: use the clean venv, NOT system python3 (see below)
.ci-mirror-venv/bin/python -m pytest steam_backlog_enforcer/tests/ -q   # ~21s

# before each commit
pre-commit run --files $(git diff --cached --name-only | tr '\n' ' ')

System python3 has mcp 2.0.0 but requirements.txt pins mcp<2, so test_mcp*.py fails to collect and coverage reports ~97%. That is a local environment artifact, not a regression — use .ci-mirror-venv/bin/python for anything coverage-related. Do not "fix" it by moving the pin.

Long jobs (scripts/ci_mirror.sh, full-suite runs) go in the background with run_in_background: true rather than a long foreground timeout.

Done condition

• bash scripts/check_file_length.sh --all → exit 0, and the todo's literal bash ~/utils/scripts/check_file_length.sh --all → exit 0 (running both catches drift between the vendored copy and upstream).
• .ci-mirror-venv/bin/python -m pytest steam_backlog_enforcer/tests/ -q → green at exactly 100%.
• Full-tree pylint → 10.00/10, with --fail-under=10.0 committed.
• pre-commit run --all-files passes.
• A staged 251-line file still makes git commit fail.
• ./run.sh runs and its output is unchanged. To prove a refactor is behaviour-preserving despite live Steam state changing under you, compare against a worktree at HEAD rather than an older captured baseline: git worktree add --detach /tmp/wt HEAD and diff the two runs.

Verify

Run the enforcer entry point, show the output, and confirm with the user. Do NOT restart the systemd unit or Steam — a real total-block/manual-pick lock may be active on this machine; ask first.

REMOVE ME AFTER FINISH