DOC: Add prose-budget for committed text and warning-level commit-msg hook#6241
Merged
hjmjohnson merged 1 commit intoMay 8, 2026
Merged
Conversation
3a944b9 to
58c6d25
Compare
dzenanz
approved these changes
May 8, 2026
This comment was marked as resolved.
This comment was marked as resolved.
Codifies hard caps for the three artifacts that carry committed
text (in-source comments, commit-message bodies, PR visible
summaries) and forbids transient URLs, marketing language, AI
tool/session attribution, first-person narrative, and references
to deleted code. Adds a commit-msg hook that warns on body length
or forbidden patterns; ITK_PROSE_BUDGET_HARD=1 escalates to
blocking.
Adds Documentation/AI/{prose-budget,code-comments,community-feedback}.md
and updates AGENTS.md, git-commits.md, pull-requests.md to wire
in the new contract.
58c6d25 to
ea392f9
Compare
f5d5f29
into
InsightSoftwareConsortium:main
13 of 16 checks passed
50 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Codify hard caps for committed text and add a warning-level commit-msg hook so reviewers stop being asked to redo the same "trim the prose" round-trip on every PR.
What this PR changes
Two new docs, one new hook, three doc edits, one config wire-in.
Documentation/AI/prose-budget.mdDocumentation/AI/code-comments.mdDocumentation/AI/community-feedback.mdDocumentation/AI/git-commits.mdDocumentation/AI/pull-requests.md<details>) with forbidden-content list.AGENTS.mdUtilities/Hooks/kw-prose-budget.pyITK_PROSE_BUDGET_HARD=1) flagging body-length / line-width / forbidden-pattern violations..pre-commit-config.yamlkw-commit-msg.Caps at a glance
kw-commit-msg.py)<details>blocksForbidden in committed text
Hook behavior
The new
kw-prose-budget.pyruns at commit-msg stage alongsidekw-commit-msg.py. By default it prints warnings and exits 0 (commit allowed); setITK_PROSE_BUDGET_HARD=1to escalate to blocking. The patterns are conservative — reviewers remain the authoritative gate; the hook reduces round-trips by surfacing the most-cited rejection patterns at commit time.Smoke-tested locally on a synthetic verbose body — flags transient URLs, AI tool names, marketing language, line-width and line-count caps; allows the commit through with a
1 warning(s); commit allowed.summary line.