S11 (#197) — living docs described code #148 deleted; the doc guard's ban list was never updated

[Polichinel]

Closes #197. Finishes #154. Part of epic #181.

What #154 left behind

Closed 2026-08-01. ADR-012 was corrected; the rest was not. Re-counted by reading each hit rather than grepping:

document	live falsehoods	deliberate retirement records
README.md	2	0
docs/architecture/role_and_seams.md	1	4
views_postprocessing/unfao/managers/README.md	6	0
docs/CICs/UNFAOPostProcessorManager.md	1	3

Correction to my own issue text: #197 said "18 stale references" from a mechanical grep and implied all were defects. Ten were. role_and_seams.md and the CIC had largely been done properly by #154 — they narrate retirements on purpose. The two READMEs were never touched at all.

The manager README

Wrong in six places, and it sits inside the package next to the code it describes:

• Template Method documented as _transform → _append_metadata — deleted in S1 — Delete the retired delivery path; refuse an incomplete config #149
• points readers at tests/test_append_metadata.py — deleted in S1 — Delete the retired delivery path; refuse an incomplete config #149
• a Clip stage (_clip_observed_history) that no longer exists
• unfao/extraction.py and unfao/gaul_schema.py — moved to contract/ in S5 — Separate partner declarations from delivery machinery #153
• "Appwrite settings are read from the environment via os.getenv (no startup validation yet — tracked in Add timeout to Appwrite download and upload operations (C-13) #11)" — false: þing-01 [þing-01] Kill the implicit ensemble-dotenv borrow; entry validation per D6 #134 added fail-loud assert_env_declared, and Add timeout to Appwrite download and upload operations (C-13) #11 is about timeouts
• called the manager a "thin orchestrator" — the word ADR-012 deliberately replaced with a number

Rebuilt against the real methods, with the 406/450-line budget and the one-views_pipeline_core-importer property stated as the checkable facts they are.

Not everything was a defect

role_and_seams.md's Seam B says of itself: "This section described the state until 2026-07-27; it is no longer true and is kept because the shape of the fix is worth reading." Deleting that would remove the reasoning for the frame-native path.

Those lines got the repo's existing line-scoped legacy-ok marker instead of edits, and the retired methods are recorded in a small table — what it was and where the work went. A phase table with a gap is worse than one that answers the question.

A new test pins that the marker stays line-scoped: one that leaked to the whole file would silently disable the guard it excuses.

The ban list — the actual mechanism

_BANNED carried five ADR-011-era symbols and nothing was added when #149 deleted a delivery path and #153 moved the machinery. The guard was not wrong. It was not updated. Now 19 entries, grouped and dated by the PR that deleted each, with a (?<!FAO_)PGMDataset lookbehind so views-faoapi's live FAO_PGMDataset is spared.

Mutation-tested: reverting to the five pre-S11 entries fails two of the new tests.

Review findings — all four addressed

F1 (warning) — the failure message had been reduced to doc.name so the helper could take tmp_path docs. Three living docs are named README.md, so a failure said README.md:28 and could not say which. Restored to repo-relative with a fallback.

F2 (warning) — I wrote into the CIC that "forecast shards carry their provenance in the ADR-013 run manifest." They do not. Verified against run_manifest.py: the keys are exactly contract_version, run_id, targets, shards, expected_months, expected_cell_count, sidecar — no lookup_version, region or unmapped_count. The forecast side's guarantee is identity and integrity, not the C-15 field set.

Writing an unverified claim into a contract document, in the story about unverified claims in documents, is the habit this epic exists to break. Corrected, then checked by script — which caught a second slip, prose saying "shard hashes" where the key is shards.

F3, F4 (suggestions) — the membership loop's docstring now says what it can catch (an entry going missing) and what nothing can (a deletion whose symbol nobody adds — only the habit covers that); the IGNORECASE inheritance on the lookbehind is noted.

Verification

ruff check .                                     # clean
pytest -q                                        # 316 passed, 44 xfailed, 5 known pyarrow (C-72)
pytest -q tests/test_doc_accuracy.py             # 10 passed
git diff --stat origin/main -- tests/fixtures/   # empty

Plus a script asserting the CIC names all 7 manifest keys and that the three it declares absent are absent, and test_internal_doc_links_resolve green after the rewrites.

🤖 Generated with Claude Code