Clear the snippet prose backlog, exemptions first

[ptr727]

Closes part of #519: catalog/snippets/ is now at zero prose findings. The whole tree goes from 557 across 45 files to 373 across 26.

Snippets led because a non-conformant snippet seeds its violations into every repo that adopts it, and the downstream repo is then flagged for content it was handed. That is a seeding-risk ordering rather than a size one: the three biggest files in the tree are not snippets at all.

The exemptions were fixed before the corpus

The findings were read as a hypothesis, not a work list. prose_lint's comment rules ban a construction rather than a detectable subset of it, so the exemptions carry the whole burden of encoding the legitimate uses, and a stale one hands out a work list that damages correct files. Three of the 184 snippet findings were exemption misses.

A comment body that is one token closing on a colon is a key or a heading. # ignore: heading a commented-out block in codecov.yml is disabled configuration, so the capitalization comment-case asked for would corrupt the key a repo uncomments. Measured tree-wide, the shape matches exactly two bodies, both a key or a heading. The broader reading of "a body with no whitespace at all" covers 99 and sweeps in every reference URI and v3.2.0 marker with them, which is why the narrow shape was taken.

A label opening a definition names the thing being defined. # publish - 'true' when ... documents an output named publish, so capitalizing it renames what the workflow declares. This is the comment spelling of the - **Label** - text construct the dash rule already exempts.

The first design here was wrong, and only the corpus said so. A bare ^word - reading matches six comment bodies, but two of them are wrapped continuations whose dash is parenthetical, which is precisely the construction the dash rule exists to catch. Both continuations follow a line that does not end a sentence, so scoping the exemption to a line that opens a definition excludes them structurally. The corpus chose the unit; a test locks that case.

A definition list keyed on a code span needed no checker change at all. - latest - the current stable release. is flagged because LABEL_DASH requires a **bold** label. Following the finding's own message ("spaced hyphen -> a comma, two sentences, or parentheses") would have destroyed the list. - **latest** - text is already exempt and is the form GOVERNANCE.md and docs/devcontainer.md use, so bolding the label is the fix and the code span survives inside it. 17 such lines exist tree-wide; the 2 in snippets are fixed here.

Verdicts diffed in both directions, before any prose was touched

Whole-tree, old against new:

• Went silent: exactly the three misses above.
• Newly reported: nothing.

Five tests lock the two new arms, including test_a_continuation_dash_is_not_read_as_a_label, which is the design that was rejected. Verified against the pre-change checker in an isolated copy: the new tests fail there and pass here.

Cost, stated rather than left to be found

The label exemption costs a detection: a comment that genuinely opens a sentence on one word followed by a spaced dash is no longer read as a lowercase opening. scripts/README.md records this alongside both new exemptions.

comment-case still reports a comment opening on a lowercase identifier (# isinstance guard first: ..., # consumerModel has no defaults fallback ...). That is 23 of the remaining findings and the rule intends them restructured rather than exempted, so nothing here widens to cover them.

Two open questions on #519, answered

Neither answer was recorded on the issue, and both are now in TODO.md:

1. Is reports/** exempt? Yes, as a generated tree.
2. Are snippets higher priority? Yes, which is this pull request's whole ordering.

The issue's own headline numbers (668 total, 119 hand-authored at 69688ec) are stale, computed before comment-wrap/comment-case joined DEFAULT_RULES and before reports/ became exempt.

Verification

Every gate in OPERATIONS.md "Run the gates the way CI runs them", from this checkout:

• test_prose_lint.py 195 tests OK, test_repo_gate.py 23 OK, test_pr_review.py 103 OK
• spec/audit.py --selftest SELFTEST PASS, spec/validate.py OK, repo_gate.py 0 issues
• Gating prose run (charset/dupword/spelling) exits 0
• editorconfig-checker clean, jq empty clean over every JSON glob
• --diff origin/develop exits 0, so nothing this branch touches carries a finding

Line endings were checked explicitly rather than assumed: no file changed EOL style and none has mixed endings. The git diff --check trailing-whitespace warnings are pre-existing CR in CRLF files, which text: unset leaves alone.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This pull request reduces (and in catalog/snippets/**, eliminates) prose_lint findings by (1) tightening/adding two targeted comment-case/comment-wrap exemptions that protect commented-out configuration keys and definition-label comments, (2) adding regression tests documenting the intended boundary behavior, and (3) rewriting snippet comment prose to conform to the gate without changing the underlying workflow semantics.

Changes:

• Extend scripts/prose_lint.py to exempt (a) one-token KEY: comment bodies and (b) definition-label comment lines from comment-case, while preserving comment-wrap behavior for wrapped continuations.
• Add regression tests for the two new exemption arms plus the key boundary cases (colon-ending prose, continuation-dash wrap, and run-on visibility).
• Rewrite snippet YAML/Markdown/shell comments and snippet docs to satisfy the prose rules, and update TODO.md to reflect the post-snippets backlog state.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
TODO.md	Updates the #519 backlog narrative and measured counts now that catalog/snippets/ is clean; adds a missing reference link.
scripts/test_prose_lint.py	Adds tests locking the new comment-case exemptions and ensuring they do not hide real prose or continuation wraps.
scripts/README.md	Documents the two new exemption rationales and their explicit detection tradeoff.
scripts/prose_lint.py	Implements KEY_ONLY and COMMENT_LABEL exemptions in comment_wrap_findings to avoid corrupting commented configuration keys and definition labels.
catalog/snippets/workflows/run-periodic-codegen-pull-request.yml	Rewraps concurrency comments into one-sentence-per-line form without changing behavior.
catalog/snippets/workflows/README.md	Adjusts prose to avoid dash-rule constructions and clarify guarantee references.
catalog/snippets/workflows/publish-plan-task.yml	Restructures comment prose (including the publish/stable definition labels) to comply with comment-case/wrap rules.
catalog/snippets/workflows/publish-docker-readme-task.yml	Rewrites long comments into compliant single-sentence lines while preserving meaning.
catalog/snippets/workflows/get-version-task.yml	Rewraps explanatory comments for the same prose-lint compliance goal.
catalog/snippets/workflows/check-upstream-version-task.yml	Rewraps and clarifies comments; keeps contract details intact.
catalog/snippets/workflows/build-release-task.yml	Rewraps and clarifies multi-line explanatory comments; no logic changes.
catalog/snippets/workflows/build-pypilibrary-task.yml	Rewraps comments and clarifies smoke/publish behavior without changing steps.
catalog/snippets/workflows/build-nugetlibrary-task.yml	Rewraps comments to satisfy prose rules; no workflow logic changes.
catalog/snippets/workflows/build-executable-task.yml	Rewraps comments for smoke mode and artifact behavior; no semantic change.
catalog/snippets/workflows/build-docker-task.yml	Rewraps comments around smoke/QEMU/login/cache behavior; no semantic change.
catalog/snippets/workflows/build-datebadge-task.yml	Rewraps the header comment into compliant prose.
catalog/snippets/vscode/README.md	Converts definition-list labels to the bold-label form already exempted by the dash rule.
catalog/snippets/husky/README.md	Rewrites prose to avoid dash-rule triggers and sentence-wrap findings.
catalog/snippets/husky/pre-commit	Splits multi-sentence comments into compliant per-line sentences.
catalog/snippets/devcontainer/python/post-create.sh	Rewraps explanatory comments into one sentence per line while keeping intent unchanged.
catalog/snippets/configs/docker-hub-readme.md	Changes definition-list labels to the bold-label form to satisfy the dash rule while preserving code spans.
catalog/snippets/configs/dependabot.yml	Rewraps explanatory comments to avoid wrap/case findings.
catalog/snippets/configs/codecov.yml	Rewrites comments to avoid dash-rule and wrap/case findings while preserving meaning.