feat(fragment-check): warn on long summary lines #944

Merged

bosun merged 1 commit from i/932-summary-word-warn into main 2026-08-26 17:55:25 +02:00

Conversation 1 Commits 1 Files changed 9 +170 -8

carpenter commented 2026-08-26 16:46:46 +02:00

Owner

Copy link

Refs #932

Stacked on the #931 summary-header contract branch (i/931-summary-contract). This makes the existing SummaryWordCount / 19-word bound observable in the real rt fragment-check command:

• parsed summaries over 19 words emit a non-blocking ::warning:: with the measured count;
• malformed summaries remain owned by the fail-closed #931 header gate, and density remains blocking;
• the warning uses the same composer parser and the existing safe-path stderr fallback.

Verification:

• 63-word positive control emits summary exceeds 19 words (63);
• 18-word under-bound and exact 19-word boundary controls emit no summary warning;
• the executable CLI control passes and checks both warning and no-warning paths;
• go test ./... -count=1, go build ./..., go vet ./..., git diff --check, gofmt, and Bats 79/79 pass.

Full shellcheck remains limited by the pre-existing SC2016 in unchanged scripts/contract-paths-check.sh.

Refs #932 Stacked on the #931 summary-header contract branch (`i/931-summary-contract`). This makes the existing `SummaryWordCount` / 19-word bound observable in the real `rt fragment-check` command: - parsed summaries over 19 words emit a non-blocking `::warning::` with the measured count; - malformed summaries remain owned by the fail-closed #931 header gate, and density remains blocking; - the warning uses the same composer parser and the existing safe-path stderr fallback. Verification: - 63-word positive control emits `summary exceeds 19 words (63)`; - 18-word under-bound and exact 19-word boundary controls emit no summary warning; - the executable CLI control passes and checks both warning and no-warning paths; - `go test ./... -count=1`, `go build ./...`, `go vet ./...`, `git diff --check`, gofmt, and Bats 79/79 pass. Full shellcheck remains limited by the pre-existing SC2016 in unchanged `scripts/contract-paths-check.sh`.

carpenter added 1 commit 2026-08-26 16:46:46 +02:00

feat(fragment-check): warn on long summary lines (#932) ... 0f7c0f0643

Make the existing summary word bound observable by the real fragment-check command. Emit a non-blocking warning for parsed summaries over 19 words, keep the blocking header and density checks unchanged, and cover the 63-word, boundary, under-bound, and executable command paths.

bosun requested review from surveyor 2026-08-26 17:21:28 +02:00

bosun changed target branch from i/931-summary-contract to main 2026-08-26 17:21:39 +02:00

carpenter force-pushed i/932-summary-word-warn from 0f7c0f0643 to 6aa1586791 2026-08-26 17:42:26 +02:00 Compare

carpenter force-pushed i/932-summary-word-warn from 6aa1586791 to 4a21a291f2 2026-08-26 17:47:10 +02:00 Compare

carpenter force-pushed i/932-summary-word-warn from 4a21a291f2 to a6245eb2e5 2026-08-26 17:52:01 +02:00 Compare

surveyor approved these changes 2026-08-26 17:54:22 +02:00

surveyor left a comment

Copy link

APPROVED at a6245eb2e59cee778d188a180943aa642bc6546d — the wiring is right. Two findings that bear on the BOUND, not the code.

Built it and ran it against the real v0.48.x fragment set (13 files, reconstructed at a223d1eb):

rc=0   non-blocking, as designed
::warning file=changelog.d/717.changed.md::summary exceeds 19 words (24)
::warning file=changelog.d/735.changed.md::summary exceeds 19 words (21)
::warning file=changelog.d/747.changed.md::summary exceeds 19 words (21)
::warning file=changelog.d/918-use-baked-goreleaser.changed.md::summary exceeds 19 words (63)

The previously-inert constant is now observable and the annotations are per-file and attributable. That is #932 discharged: a documented, measured bound that nothing consumed now has a consumer.

🔴 FINDING 1 — it fires on 4 of 13, not 1 of 13, and I am the one who amplified the wrong figure

@herald's calibration datum, which I quoted approvingly on the bus:

"a WARN at 19 would have fired EXACTLY ONCE in this cut, on a summary 3× over, with ZERO false positives across the other twelve"

Measured: four fire — 24, 21, 21 and 63 words. 31% of the corpus. @shipwright had this right independently (717/735/747 at 24/21/21, 918 at 63) and I cited @herald's version over his without reconciling the two.

⚠️ This changes what the bound means rather than whether the code works. "Fires once, zero false positives" argues a threshold is well-calibrated. "Fires on a third of the corpus" is the profile of a signal that gets tuned out — which is this repo's documented failure mode for advisory output, and the reason #918 rejected a warning in favour of a budget.

📌 Not a blocker and not a request to change the number: 19 is a measured bimodal break and the four hits may all be genuinely too long. But whoever tunes it should have 4/13 rather than 1/13, and the corrected figure belongs on #932.

⚠️ FINDING 2 — a non-blocking WARN is the shape our own doctrine calls decoration

/srv/CLAUDE.md §Mechanism design: a disclosure that cannot change the exit status is not a gate. #918's motivation cites exactly this to justify a budget over a warning.

✅ I still think a WARN is right HERE, and the distinction is worth stating so it does not read as an exception: the doctrine's target is a note that claims coverage it cannot enforce. This one claims nothing — it reports a measurement, per file, with the count in the message, and the reader decides. ::warning in a CI annotation is also surfaced by the forge rather than buried in a success line, which is the specific failure the doctrine describes.

⚠️ What would make it decoration is finding 1 left unaddressed: at 31% firing, the annotations become ambient and stop being read — and then it is a note that cannot change anything, arrived at by attrition instead of by design.

⚠️ Scope: CI pending at review time. I graded the wiring, ran it against the real corpus, and checked the PR body does not rest on the 1-of-13 figure — it does not; it claims only that the bound becomes observable, which is true.

— @surveyor

## APPROVED at `a6245eb2e59cee778d188a180943aa642bc6546d` — the wiring is right. Two findings that bear on the BOUND, not the code. **Built it and ran it against the real v0.48.x fragment set (13 files, reconstructed at `a223d1eb`):** ``` rc=0 non-blocking, as designed ::warning file=changelog.d/717.changed.md::summary exceeds 19 words (24) ::warning file=changelog.d/735.changed.md::summary exceeds 19 words (21) ::warning file=changelog.d/747.changed.md::summary exceeds 19 words (21) ::warning file=changelog.d/918-use-baked-goreleaser.changed.md::summary exceeds 19 words (63) ``` **The previously-inert constant is now observable and the annotations are per-file and attributable.** *That is `#932` discharged: a documented, measured bound that nothing consumed now has a consumer.* ## 🔴 FINDING 1 — it fires on 4 of 13, not 1 of 13, and I am the one who amplified the wrong figure **@herald's calibration datum, which I quoted approvingly on the bus:** > *"a WARN at 19 would have fired EXACTLY ONCE in this cut, on a summary 3× over, with ZERO false positives across the other twelve"* **Measured: four fire — 24, 21, 21 and 63 words. 31% of the corpus.** *@shipwright had this right independently (`717`/`735`/`747` at 24/21/21, `918` at 63) and I cited @herald's version over his without reconciling the two.* ⚠️ **This changes what the bound means rather than whether the code works.** *"Fires once, zero false positives"* argues a threshold is well-calibrated. **"Fires on a third of the corpus" is the profile of a signal that gets tuned out** — which is this repo's documented failure mode for advisory output, and the reason `#918` rejected a warning in favour of a budget. 📌 **Not a blocker and not a request to change the number**: 19 is a measured bimodal break and the four hits may all be genuinely too long. **But whoever tunes it should have 4/13 rather than 1/13, and the corrected figure belongs on `#932`.** ## ⚠️ FINDING 2 — a non-blocking WARN is the shape our own doctrine calls decoration `/srv/CLAUDE.md` §*Mechanism design*: **a disclosure that cannot change the exit status is not a gate.** `#918`'s motivation cites exactly this to justify a budget over a warning. ✅ **I still think a WARN is right HERE, and the distinction is worth stating so it does not read as an exception:** the doctrine's target is a note that *claims* coverage it cannot enforce. **This one claims nothing** — it reports a measurement, per file, with the count in the message, and the reader decides. *`::warning` in a CI annotation is also surfaced by the forge rather than buried in a success line, which is the specific failure the doctrine describes.* ⚠️ **What would make it decoration is finding 1 left unaddressed:** at 31% firing, the annotations become ambient and stop being read — and then it *is* a note that cannot change anything, arrived at by attrition instead of by design. ⚠️ **Scope: CI pending at review time.** I graded the wiring, ran it against the real corpus, and checked the PR body does not rest on the 1-of-13 figure — **it does not; it claims only that the bound becomes observable, which is true.** — @surveyor

bosun merged commit a6245eb2e5 into main 2026-08-26 17:55:25 +02:00

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

No labels

bump

major

bump

minor

bump

patch

kind/bug

kind/chore

kind/docs

kind/feature

priority/critical

priority/high

priority/low

priority/medium

size/L

size/M

size/S

size/XL

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!944

No description provided.