fix(quality): drop overflow Tier 2 companions instead of a doomed cluster

[alimobrem]

Root cause

The user ran Scan on pulse-agent and the run appeared to produce nothing new — same reused PR (PulseSRE/pulse-agent#2), surrounded almost entirely by WARNING-severity "refused"/"could not converge" events.

Investigation (Postgres events/deliveries, live pod logs, oc cluster access) traced this to a real regression in PR #213 (_attach_companions_to_clusters()), deployed to the cluster at 2026-07-29T19:51:16Z — squarely between two consecutive Scans on the same app, the first of which (19:41Z, pre-deploy) showed none of this behavior and the next two (20:16Z/20:21Z, post-deploy) both did.

partition_by_finding_cluster()'s Tier 2 "companion" rescue attaches extra generated files to an existing same-layer Tier 1 fix cluster. When every same-layer cluster was already at MAX_FILES_PER_CLUSTER_PR, the overflow path spilled the leftover companions into a brand-new <key>-also-included-N cluster that inherited the base cluster's target_findings — e.g. container / dockerfile_pin. But that new cluster's only files are companions, which by definition never clear that finding. clear_evidence_simulation_ok() downstream therefore refused it unconditionally, every single time:

Auto-delivery cluster container-also-included-1 for pulse-agent refused: Clear-evidence
simulation failed — refusing PR (MERGE would not clear the finding): `container`
(dockerfile_pin): dockerfile.fast: not staged ...

This never blocked the real fix (the Tier 1 container cluster still delivered and updated PR #2 fine), but it wasted a full validation pass and logged confusing "refused" warnings on every Scan, making a successful run look like a failure. The existing test (test_companion_overflow_spills_into_a_new_chunk) only asserted the overflow cluster's shape — it never ran that cluster through the clear-evidence gate with real, non-clearing companion content, which is exactly why the local suite (mocks/fixtures) missed this and it only surfaced against live pulse-agent data.

Fix

Overflow companions with no same-layer room left are now dropped, exactly like a companion whose layer matches no Tier 1 cluster at all — never spun into a new cluster that's mathematically guaranteed to fail its own gate.

Testing

• Added test_companion_overflow_is_dropped_not_spilled_into_a_doomed_cluster, test_companion_overflow_cluster_would_have_failed_clear_evidence, and test_pulse_agent_container_incident_reproduction (uses the real container/containerfile/otel_setup.py-shaped data from the live incident).
• Verified all three fail against the pre-fix code (confirmed via git stash) and pass with the fix.
• Full suite: 3518 passed, 454 skipped (no regressions).
• Updated CHANGELOG.md, docs/release-notes.md, and README.md per repo convention.

Not merging — opening for review per usual process.

Made with Cursor