Stop the QC dashboard asserting a coverage target nothing can reach (#325)

[realmarcin]

Addresses the part of #325 that is actionable from this repo. The preferred fix is blocked upstream — see below.

The issue's preferred option cannot be done here

Adopt the history/ provenance layer … and have the QC config point timestamp_paths at it instead.

_corpus_timestamp(records, paths) in the shared generator reads from records — the YAMLs under yaml_dir. timestamp_paths selects a dotted path within each record, not an alternate directory. So it cannot name history/, and no config change here reaches it.

The history/ tree does exist and is being written to (2 entries, each carrying session.timestamp in the shape the dashboard wants). The layer is real; the dashboard simply can't read it. Filed as #491.

What is fixable here

conf/qc_config.yaml asked for 90% curation_history coverage against 0.6% actual — 2 records of 312. That slot could only ever clear via a bulk backfill of 310 records, which is the open question in #325 rather than something curation closes. So it had been warning permanently, and a gate in that state teaches its readers to skip past it. The next slot to go genuinely wrong inherits the habit.

Set to 0.0, matching the discussions precedent already in the file: honest that there is almost no data, never blocking. Raise it when coverage actually grows — which it now can, since #395 made every gtdb_ground.py write append an event, so a grounding sweep records itself.

The distinction the new test draws

A threshold may sit above current coverage — that is what a target is — but not so far above that no plausible curation closes it:

slot	asks	has	verdict
associated_datasets	0.30	0.282	six records short — a target
curation_history	0.90	0.006	a factor of 150 — not a target

tests/test_qc_thresholds_are_reachable.py sweeps every slot with a deliberately loose 3× allowance, so aspirational targets stay legal. Every other slot passes today.

Mutation-checked: restoring 0.90 fails two tests.

One thing that makes #325 less urgent than filed

The dashboard already labels the thin base on its face:

Latest curation 2026-07-02T00:00:00+00:00 (from 2 of 312 records)

_corpus_timestamp's docstring says "a date resting on 2 of 311 records deserves to be labelled as such" — and it does. The gap is visible, not silent, which is the opposite of what the issue feared.

What stays open

Whether to backfill the other 310. Git could supply a date per file, but that dates the file rather than the curation, and writing 310 provenance entries whose timestamps mean something other than what the field claims is a curation-workflow decision — which is where #325 leaves it too. Not mine to make.

2350 passed, 16 skipped. ruff, black clean. Dashboard regenerated (it is tracked).

🤖 Generated with Claude Code

[realmarcin]

Self-review (the review agent hit a session limit before starting)

I ran its two crux checks myself rather than assuming.

Check 1 — does the test measure what the generator enforces? Yes.

A test asserting "thresholds are reachable" is worthless if it computes coverage differently from the thing that enforces them. Compared _coverage() against kg_microbe_qc._score() slot by slot, same 312 records:

id 1.0000/1.0000  environment_term 0.9872/0.9872  taxonomy 0.9936/0.9936
curation_history 0.0064/0.0064   associated_datasets 0.2821/0.2821  ...
mismatches: 0

Check 2 — does 0.0 hide the gap? No, but it does trade a signal.

The dashboard row reads:

curation_history    2 / 312    0.6%    0%    PASS

The count, the percentage and the floor-level threshold are all on the face of it — a reader sees the slot is nearly empty and that nobody is asking otherwise. What changes is that the status stops being a WARN.

Stating the counter-argument plainly, since it has force: the WARN was a standing reminder that provenance coverage is 0.6%, and 0.0 removes the only status-level signal. My judgement is that a warning which cannot be cleared by any amount of curation is noise rather than signal, and the numbers remain visible either way — but that is a judgement, not a fact, and it is reversible in one line.

What I found while checking: my own rule was a rationalisation

REACHABLE_FACTOR = 3.0 alone collapses on a near-empty slot. At 0.6% coverage it permits at most 1.9%, so the only legal non-zero target is a rounding error — and a curator wanting "grow curation_history to 10%" is forbidden from saying so. The rule therefore permitted exactly the 0.0 this PR chose and essentially nothing else. That is not a rule.

Added REACHABLE_MARGIN = 0.10, applied as max(actual * 3, actual + 0.10):

slot	coverage	ceiling	is 0.90 legal?
curation_history	0.64%	10.64%	no
associated_datasets	28.21%	84.63%	no

Mutation-checked both directions — restoring 0.90 still fails; a legitimate 0.10 growth target now passes, where before it did not.

---

2350 passed, 16 skipped. ruff, black clean.

Not checked, and worth someone's eye before merge: whether dashboard/ regenerates deterministically. It is a tracked generated artifact with no freshness gate, so it can drift exactly as docs/ did before #477 — that would be its own issue rather than a blocker here.