Remove the five scripts that never ran, and guard the cause (#410, #523)

[realmarcin]

What was left of #410

All five remaining scripts began from communitymech.literature_enhanced import EnhancedLiteratureFetcher. That module is absent from all 498 commits — including the one that added the scripts. They fail at import; even --help does not work.

#487 already fixed the one working tool that invoked one. What remained was the decision the tests recorded as deliberately open: port them, or drop them.

Dropped, and why

Porting was never an import swap — the scripts' own docstrings say so. Their CLI flags advertise a 6-tier PDF cascade with "fallback mirrors"; LiteratureFetcher has no PDF surface at all. A port meant building that, and retrieving publisher PDFs through mirrors is not something to add speculatively.

The real need underneath is open-access full text, and scripts/cache_fulltext.py already serves it — the #183 sweep used it to cache full text for 64 of 125 references. Reversible: git revert brings them back, and a test says what they'd need first.

The guard is the more useful half

_KNOWN_BROKEN was five names plus three tests keeping the list honest. That records breakage; it does not prevent it — a sixth script importing a sixth phantom module would just have joined the list.

test_no_script_imports_a_module_that_does_not_exist now resolves every from communitymech.X import ... in scripts/ against the installed package, so the next one fails when it is written. The list stays, empty, because the removed names are still dead pointers for any tool that prints them.

Two things the existing tests caught

1. Emptying the constant made it _KNOWN_BROKEN: set[str] = set() — an AnnAssign. The sibling test's Assign-only AST walk stopped finding it and went red rather than passing on an empty set.
2. assert len(dead) >= 5 would have started passing on nothing. It now rests on the removed names — a gone file is as dead a pointer as one that cannot start.

test_that_guard_can_actually_fail exists because a list-driven check passes cleanly once its list is empty, which is exactly this file's new state.

Round two: the docs (#523)

Nothing walked docs/ for script references — both guards check scripts/ only, and a curator following a runbook is reading prose. Three docs and .gitignore said "NOT FUNCTIONAL … tracked in #410", true until this PR and now stale in a new way: the files are gone, so a reader can't tell deletion from being on the wrong branch. They now say REMOVED and name the replacement.

I filed #523 on a false premise and corrected it. I claimed AUTOMATION_TOOLS.md gave a bare unwarned instruction. It didn't — the warning sat two lines above the command, and I had grepped for the script name and read only the matching line. Third time this session a line-scoped scan missed the prose that negates the hit. The test that resulted checks existence, not tone: whether a reference is adequately caveated is a judgement, whether the file exists is a fact, and only the fact belongs in a test.

pdf_fetching_capability.md is exempt by name — it carries a document-level banner that a per-line check cannot see, and rewriting it would destroy the record it exists to keep.

Checks

• uv run pytest tests/ — 2371 passed, 16 skipped
• just validate-strict, just lint, just check-docs-current — exit 0
• 62 scripts remain; none import an unresolvable communitymech module
• Mutation-checked: appending a reference to a nonexistent script reddens the docs guard

Closes #410, closes #523.

🤖 Generated with Claude Code