Skip to content

S2 (#183) — close Cluster K's three finished entries; make register closing conditions machine-checkable - #194

Merged
Polichinel merged 1 commit into
developmentfrom
feat/s2-close-cluster-k
Aug 1, 2026
Merged

Polichinel merged 1 commit into
developmentfrom
feat/s2-close-cluster-k

Conversation

@Polichinel

Copy link
Copy Markdown
Collaborator

Closes #183. Part of epic #181.

What was actually wrong

Three entries sat under ## Open Concerns with nothing outstanding.

entry its own words reality
C-43 "closes when tests/test_gaul_lookup_fidelity.py is committed and green" committed in #141, 18 passed
C-59 "Mitigation — landed 2026-07-31" test_builder_rejects_a_duplicate_gid, test_lookup_key_is_unique — both exist, both pass
C-61 "Mitigation — landed 2026-07-31" test_a_sentinel_code_is_dropped_rather_than_shipped, test_lookup_carries_no_sentinel_codes — likewise

scripts/build_gaul_lookup.py carries zero bare assert statements and four LookupBuildError raises. The work was done on 31 July.

C-43's scope, preserved

The paragraph that must survive retelling: this closes transcription fidelity — that this repo faithfully carries views-datafactory's area-majority assignment through to the partner. It does not close assignment correctness. If the producer's join puts a cell in the wrong country, every check still passes and FAO still receives a confidently wrong label. That is views-datafactory#387, and this repo is structurally incapable of judging it.

Verified independently of the tests: C-43's block survived the move at 10,737 chars with SCOPE, assignment correctness, views-datafactory#387 and the TRIGGER FIRED history intact. 86 entries before and after.

The guard, which is the point

test_register_integrity.py could already catch a heading that says resolved. It could not catch an entry saying open while the thing it waited for had arrived — this register's actual failure mode, six times in two days.

Two checks, both mutation-proven against the real 2026-08-01 register:

AssertionError: open concern(s) whose own stated closing condition is already met —
  the named artifact exists. […]: ['C-43 -> tests/test_gaul_lookup_fidelity.py']

AssertionError: open concern(s) recording a landed mitigation: ['C-59', 'C-61'].
  Either move the entry to Resolved, or write 'Partial mitigation' and state what remains.

Restored: 10 passed.

Review findings — all four addressed

F1 (warning) — _ARTIFACT_ROOTS contradicted its own stated design. The comment says "prefer false negatives; a guard that cries wolf gets deleted", and the list then included docs/ and .github/. For tests/ and scripts/, existence is close to the condition because the suite runs them. For docs/, they come apart entirely — an ADR file has existed since July while the section an entry waits on may never have been written.

The margin was thin, not hypothetical. The one other Open entry using this phrasing is C-62: "closes when C-44's bump becomes takeable… declaring torch here against the…". It passes only because the backticked token is torch rather than a path. A doc path there would fail a correctly-open, upstream-blocked entry — and the next person deletes the guard.

Narrowed to ("tests/", "scripts/"), with the reasoning in the code. Mutation proof re-run after narrowing: still bites.

F2 (suggestion) — _open_blocks extracted to the helper section; test_every_concern_entry_declares_the_required_fields re-pointed at it. Two parsers for one document shape is how the register's drift started.

F3 (suggestion) — docstring no longer opens with four consecutive quotes.

F4 (suggestion) — comment now states that "Mitigation — landed" / "Partial mitigation" are conventions this guard enforces by exact match, so writers know the string matters.

Note for S9 (#190)

This change makes two phrases load-bearing strings in a hand-written document — a standing rule a future contributor could violate without knowing it exists. That is the ADR trigger CLAUDE.md names. Routed to S9's ADR question rather than decided here.

Verification

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

Register: 74 concerns, 22 open, 52 resolved. Cluster K mostly closed (C-60 → S5, C-46 → S7). Cluster M heading corrected to six.

🤖 Generated with Claude Code

…and make closing conditions machine-checkable

C-43, C-59 and C-61 were filed under Open with their own stated closing
conditions already met. C-43's body said it plainly — "C-43 closes when
tests/test_gaul_lookup_fidelity.py is committed and green" — and that file was
committed in #141 with 18 tests passing. C-59 and C-61 both recorded
"Mitigation — landed 2026-07-31" and named four guards that exist and pass.
Nothing was outstanding. The entries simply never moved.

All three moved to Resolved, each citing the test rather than the session, which
is what C-43 instructed. Its transcription-fidelity-vs-assignment-correctness
scope split is preserved verbatim: this closes faithful carriage of the
producer's answer, NOT whether that answer is right. The latter is
views-datafactory#387 and is not this repo's to close.

The guard this adds is the point of the story. test_register_integrity.py could
already catch a heading that SAYS resolved; it could not catch an entry saying
open while the thing it waited for had arrived — which turned out to be this
register's actual failure mode, six times in two days. Two new checks:

  - an Open entry naming a "closes when `tests/…`" artifact that exists
  - an Open entry recording "Mitigation — landed" without "Partial mitigation"

Mutation-tested against the real 2026-08-01 register: both fail, naming
'C-43 -> tests/test_gaul_lookup_fidelity.py' and ['C-59','C-61']. Restored, all
10 pass.

Deliberately narrow, and narrowed further in review. _ARTIFACT_ROOTS covers
tests/ and scripts/ only. For an executable artifact, existence is close to the
condition because the suite then runs it; for docs/ the two come apart entirely —
an ADR file has existed since July while the section an entry waits on may never
have been written. Including doc paths would fire on correctly-open entries, and
the guard would be deleted rather than fixed. That is the failure this check
exists to avoid, so it must not commit it.

Cluster K carries a closure note: one test file discharged three entries exactly
as its fix strategy predicted, and the cost was not the geography bug it was
opened for — it was that the engineering took one session and the record took two
more days. C-43's own residual said the forward-check needed attaching to
something the interpreter runs; the entries then made the identical error one
level up. A guarantee needs a check, including the register's own.

Header 25 -> 22 open, 49 -> 52 resolved. Cluster M heading corrected to six.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@Polichinel
Polichinel merged commit 2284be4 into development Aug 1, 2026
4 checks passed
@Polichinel
Polichinel deleted the feat/s2-close-cluster-k branch August 1, 2026 23:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant