Found by this repository dogfooding itself: a Ruled-out: record written while restructuring the README caused guard to flag an unrelated README proposal, breaking a does not flag case in test/guard.test.ts.
Reproduced
A history containing one record:
Ruled-out: README를 제품 진입점으로 전면 재구성 | 4개 파일 일관성 때문에 불가
Probed with a clean proposal from spec/fixtures/guard/proposals.json:
$ commitlore guard --proposal "document the exit codes in the README" --threshold 0 --json
{
"score": 0.625,
"signals": ["keyword:readme", "keyword-strength:1.00", "jaccard:0.25"]
}Default threshold is 0.35, so this flags.
What the signals say
The two strings share exactly one token: README. One is Korean, the other English, and they are about different things — restructuring a page versus documenting exit codes on it.
keyword-strength: 1.00 is the part worth looking at. Every keyword the matcher extracted from the alternative was present in the proposal, because the alternative yielded essentially one usable keyword. A short alternative gives the matcher little to work with, so a single proper noun carries full strength; jaccard: 0.25 alone would not have cleared the threshold.
Cross-language makes it sharper rather than causing it: tokenising Korean prose leaves few Latin tokens, so the shared proper noun is almost the entire overlap.
Why file it when ADR-0020 already calls guard experimental
ADR-0020 records guard as an advisory with precision measured at 44.8%, and this is consistent with that. What makes it worth its own issue is that it names a mechanism rather than restating the statistic: short alternative text concentrates keyword strength onto whatever proper noun it contains. That is inspectable and possibly fixable — for example by damping strength when the extracted keyword set is very small, or by not letting a single token reach full strength.
It also arrived the way findings should: the product's own gate caught it on the repository that ships it.
Suggested acceptance
- a proposal sharing only a proper noun with a short alternative does not reach the default threshold
- the existing measured precision does not regress on
spec/fixtures/guard/
- whatever damping is chosen is expressed in the signals, so a score stays explainable
Not a fix, and worth recording
The immediate collision was resolved by rewriting the record, not by changing guard: the alternative became Restructure the English product entry page alone | T-1015 and T-1016 enforce four-file consistency and the translations belong to #590, which stopped matching. That is better recording — it names what was actually tried instead of a category — but it is a workaround for authors, not a product fix, and the same shape recurs with any short alternative.
Found by this repository dogfooding itself: a
Ruled-out:record written while restructuring the README causedguardto flag an unrelated README proposal, breaking adoes not flagcase intest/guard.test.ts.Reproduced
A history containing one record:
Probed with a clean proposal from
spec/fixtures/guard/proposals.json:{ "score": 0.625, "signals": ["keyword:readme", "keyword-strength:1.00", "jaccard:0.25"] }Default threshold is 0.35, so this flags.
What the signals say
The two strings share exactly one token:
README. One is Korean, the other English, and they are about different things — restructuring a page versus documenting exit codes on it.keyword-strength: 1.00is the part worth looking at. Every keyword the matcher extracted from the alternative was present in the proposal, because the alternative yielded essentially one usable keyword. A short alternative gives the matcher little to work with, so a single proper noun carries full strength;jaccard: 0.25alone would not have cleared the threshold.Cross-language makes it sharper rather than causing it: tokenising Korean prose leaves few Latin tokens, so the shared proper noun is almost the entire overlap.
Why file it when ADR-0020 already calls guard experimental
ADR-0020 records guard as an advisory with precision measured at 44.8%, and this is consistent with that. What makes it worth its own issue is that it names a mechanism rather than restating the statistic: short alternative text concentrates keyword strength onto whatever proper noun it contains. That is inspectable and possibly fixable — for example by damping strength when the extracted keyword set is very small, or by not letting a single token reach full strength.
It also arrived the way findings should: the product's own gate caught it on the repository that ships it.
Suggested acceptance
spec/fixtures/guard/Not a fix, and worth recording
The immediate collision was resolved by rewriting the record, not by changing guard: the alternative became
Restructure the English product entry page alone | T-1015 and T-1016 enforce four-file consistency and the translations belong to #590, which stopped matching. That is better recording — it names what was actually tried instead of a category — but it is a workaround for authors, not a product fix, and the same shape recurs with any short alternative.