GIT017: PR merge message validation failed

Error

PR title or body doesn't follow commit message conventions for squash merge.

Why this matters

Squash merge uses the PR title and body as the final commit message. If the PR message doesn't follow conventions, it bypasses the commit validation that normally enforces them, degrading commit history on the main branch.

Common causes

PR title exceeds 50 characters
PR title doesn't follow type(scope): description format
PR body lines exceed 72 characters
Using feat(ci) or fix(test) instead of ci(...) or test(...)
PR body contains forbidden patterns

How to fix

Fix PR title

The title must follow conventional commits format:

# Good:
feat(validator): add merge validation
ci(workflow): update build matrix
fix(parser): handle empty input

# Bad:
feat(ci): update workflow  # Use ci(...) not feat(ci)
This is a very long title that exceeds the fifty character limit
Added some changes  # Missing type and scope

Fix PR body

Keep body lines within the 72 character limit:

gh pr edit <number> --body "Short summary line.

Detailed description with lines wrapped at 72 characters.
Each line should not exceed this limit.

More details here."

Add to merge command

Provide body via --body flag:

gh pr merge <number> --squash --body "$(cat <<'EOF'
Short summary.

Detailed description properly wrapped.

Signed-off-by: Your Name <your.email@klaudiu.sh>
EOF
)"

Configuration

Merge message validation settings:

[validators.git.merge.message]
enabled = true
title_max_length = 50
body_max_line_length = 72
conventional_commits = true
require_scope = true
block_infra_scope_misuse = true

To disable merge message validation:

[validators.git.merge.message]
enabled = false

To allow longer titles for reverts:

[validators.git.merge.message]
allow_unlimited_revert_title = true

Hook output

When this error is triggered, klaudiush writes JSON to stdout:

permissionDecisionReason (shown to Claude): [GIT017] PR title or body doesn't follow commit message conventions. Fix PR title/body to follow commit message conventions before merge

systemMessage (shown to user): Formatted error with fix hint and reference URL.

additionalContext (behavioral guidance): Automated klaudiush validation check. Fix the reported errors and retry the same command.

GIT004 - Title issues
GIT005 - Body issues
GIT006 - Infrastructure scope misuse
GIT013 - Invalid conventional commit format
GIT018 - Merge signoff missing

GIT017