[rwagwani]

Stacked on the whitelist-phrases PR (#313), which is stacked on #306. This PR's own change is the last commit, ce2d6e4.

Split out of #306 at @lfengad's suggestion. These are list-maintenance tools only: nothing in the request path imports them.

What it adds

• hygiene.py flags blocklist entries that two ordinary dictionary words fuse into, which is how prose collides with an entry (desk in → deskin). It reads the lists with the production reader, and its probe checks what it advises. By default it quotes only a few trademark examples that are safe to quote; everything else needs --show-entries.
• coverage.py measures what a list change stops catching. It writes five spellings of every blocklist entry (verbatim, split by a space, split by a zero-width space, fullwidth, lookalike) and runs them through is_safe, the deployed entry point. When they sit beside the lists, it also uses the exact-match list and the nltk data.

Review follow-up: comparable results

Thank you for pointing out that results were keyed by entry index and spelling, and that --compare ignored keys present on only one side. Together these let a removed or reordered entry drop out of the comparison with a clean exit. Now:

• Probe ids are stable and opaque: a SHA-256 digest of the entry, plus the spelling. Moving an entry changes nothing, and entry text is never printed.
• The probe set can be frozen with --write-probes probes.json, then replayed against both versions with --probes probes.json. An entry removed from the list keeps its probes, so its spellings show up as lost. A probe file edited after it was written is refused. The probe file holds the prompts in plain text, so it should be kept with the lists, not attached to a ticket.
• Every result file records metadata: the digest of the probe set it ran, plus digests of the blocklist, whitelist and exact-match lists and the lemmatizer used. --compare prints any of those that changed.
• --compare exits 2 with incomparable if the two runs used different probe sets, report different probe ids, or either file is not a run with probes. It never reports "lost 0" in those cases.

coverage.py <blocklist-dir> --write-probes probes.json
coverage.py <blocklist-dir> --probes probes.json --whitelist-dir <whitelist-dir> --json before.json
coverage.py <changed-dir>   --probes probes.json --whitelist-dir <changed-whitelist-dir> --json after.json
coverage.py --compare before.json after.json      # 0 nothing lost, 1 lost, 2 incomparable

New tests cover:

• a removed entry showing as lost over a frozen set;
• the same removal without a frozen set exiting 2;
• a reordered list comparing cleanly;
• each incomparable shape, including malformed and empty result files;
• an edited probe file being refused;
• case variants of an entry keeping their own probes;
• the recorded metadata.

Run on the shipped lists

• The shipped list gives 1890 probes; exact duplicate entries share one id.
• Adding desk in as a phrase, over the frozen set: lost 0, gained 0, exit 0.

Known limits

• Exact-match entries are not probed, only blocklist entries.

Tests

• pytest cosmos_framework/auxiliary/guardrail/blocklist/: 142 passed.
• ruff and pre-commit (both CI configs, all files) are clean.

🤖 Generated with Claude Code