Repository navigation
S6 — Correct ADR-012 and the manager CIC to describe what the code is #154
Description
Epic: #148 · Depends on S5 · Closes C-67
Background
ADR-012 is the repository's ontology — the document a clone's authors will read as the specification for what to copy. Two of its claims are false, and both describe exactly the structures a clone must decide about:
- "the thin
UNFAOPostProcessorManager" — it is 636 lines, 25% of the package, holding two read strategies, two save strategies, an inner port class, provenance formatting, coverage orchestration and env assembly (C-40). - "the single pandas-aware module (
unfao/extraction.py)" — pandas is imported by three modules:extraction.py,enrichment.py, andmanagers/unfao.py:14(C-65).
Both drifted the same way and for the same reason: the ADR describes the intended end state of a migration that then stopped one step short. This is the same disease as the C-48–C-55 ADR-013 audit series, which was cured by pinning prose to mechanically-checked facts.
By the time this story runs, S1–S5 will have made both claims true — the point of the story is to verify that and to pin them so they cannot drift again.
Work
- Rewrite ADR-012's ontology table against the post-S5 reality. Every row must name a location that exists and a claim that holds
- Update
docs/CICs/UNFAOPostProcessorManager.md— its guarantees were written for the two-path manager - Add the S2 retirement note if not already landed there
- Extend
tests/test_doc_accuracy.py(86 lines, already exists) so the load-bearing claims are mechanically checked: manager line count under the epic's bound, pandas importer count, the module names the ontology cites actually existing
Acceptance criteria
- Every row of ADR-012's ontology table is verifiable by a command, and the command is in the test
- No ADR-012 claim contradicts the tree — specifically the two above
- The CIC matches the post-epic manager
-
test_doc_accuracy.pyfails if the manager grows past the bound or a second pandas importer appears
Testing / validation
ruff check . · full suite green · deliberately break one claim locally and confirm test_doc_accuracy.py catches it — a doc test that cannot fail is not a test.
Activity
docs(adr): S6 — the ontology describes the code, and the claims are n…
Polichinel commentedon Aug 1, 2026
Done in PR #164. ADR-012's ontology table rewritten against the three-package structure, ADR-002's layering illustration replaced (it still named
unfao/extraction.py, deleted in #151), manager CIC updated. Register C-67 closed.Four guards added and each mutation-tested — a deliberate violation introduced, confirmed failing, reverted: pandas has exactly one importer ·
views_pipeline_corehas exactly one importer · manager under 450 lines ·contract/does not import the partner. A doc test that cannot fail is not a test.Polichinel commentedon Aug 2, 2026
Reopened in effect by #197 (epic #181, S11).
ADR-012 was corrected. The rest of this issue's scope was not — 18 references to code deleted by #149/#153 survive across four living documents, five of them in
docs/CICs/UNFAOPostProcessorManager.md, which this issue named directly.The worst is
views_postprocessing/unfao/managers/README.md: it documents the Template Method phases as_transform → _append_metadataand points readers attests/test_append_metadata.py. Both were deleted on 2026-07-31. It sits next to the code it misdescribes.tests/test_doc_accuracy.pyscans all four files, but its ban list only knows the ADR-011-era symbols (PriogridCountryMapper,geopandas, …). Nothing was added when #149 and #153 deleted a fresh set, so the guard passed over documents describing code that no longer exists.Tracked in #197, which also extends the ban list so this cannot recur silently.
docs(accuracy): S11 #197 — living docs still described code #148 dele…
Polichinel commentedon Aug 2, 2026
Finished by #199 (S11 / #197, epic #181).
ADR-012 and
docs/CICs/UNFAOPostProcessorManager.mdwere largely done here — credit where due; on reading, most of the CIC's mentions of deleted methods are correct retirement records, not errors.What this issue's scope missed was the two README files, neither touched:
README.md— the pipeline-stages table still listed_append_metadataand aClipstageviews_postprocessing/unfao/managers/README.md— wrong in six places, including_transform → _append_metadata, a pointer to the deletedtests/test_append_metadata.py, and "no startup validation yet" for Appwrite settings that þing-01 [þing-01] Kill the implicit ensemble-dotenv borrow; entry validation per D6 #134 had already made fail-loudAnd the mechanism that should have caught it:
tests/test_doc_accuracy.py's ban list was never extended past the ADR-011 symbols, so it scanned all four documents and passed. Now 19 entries with a note that a deletion PR which does not extend it has not finished.