Summary
Two surfaces state this repo's required PR-body sections, and they disagree:
| Surface |
Sections |
.github/pull_request_template.md |
Summary, Fix, Verification, Related |
.claude/source-control.md → pr_body_required_sections |
Summary, Test plan, Related |
Fix and Verification exist only in the template; Test plan exists only in the config.
Consequence
A contributor filling in the template produces a body that /source-control:pull-request create's pre-create gate would reject for a missing Test plan. An agent honoring the config produces a body missing two sections a human reviewer expects from the template.
Neither surface is wrong on its own terms — they were just never reconciled. docs/conventions/pr-body-convention/README.md is the owner doc for the key and says the drafting consumer builds one ## <heading> scaffold per required section, so the config is what actually gates PR creation; the template is what actually shapes human-authored PRs.
Today the live CI gate (pr-issue-linkage) checks only a closing keyword plus a non-empty ## Related, so nothing fails loudly — which is why this has gone unnoticed.
Observed
Filing #3162 hit this directly: I mirrored the template (Summary/Fix/Verification/Related) because that is the layout contributors see and the linkage gate keys on Related. That PR merged green while not satisfying the configured section list.
The decision to make
Which surface is authoritative:
- Template wins — update
pr_body_required_sections to Summary, Fix, Verification, Related. Keeps the richer human-facing structure; Verification is arguably a better name than Test plan for a repo whose PRs carry gate output.
- Config wins — rewrite the template to
Summary, Test plan, Related. Closer to the plugin's portable default (Summary + Test plan), simpler for contributors.
Option 1 preserves what the repo's PRs actually look like in practice. Either way the two should be edited together, and docs/conventions/pr-body-convention/README.md notes a deferred CI consumer that would validate an already-opened body against the same key — worth settling this before that lands, or it will start failing PRs on a mismatch nobody chose.
Related
Summary
Two surfaces state this repo's required PR-body sections, and they disagree:
.github/pull_request_template.mdSummary,Fix,Verification,Related.claude/source-control.md→pr_body_required_sectionsSummary,Test plan,RelatedFixandVerificationexist only in the template;Test planexists only in the config.Consequence
A contributor filling in the template produces a body that
/source-control:pull-request create's pre-create gate would reject for a missingTest plan. An agent honoring the config produces a body missing two sections a human reviewer expects from the template.Neither surface is wrong on its own terms — they were just never reconciled.
docs/conventions/pr-body-convention/README.mdis the owner doc for the key and says the drafting consumer builds one## <heading>scaffold per required section, so the config is what actually gates PR creation; the template is what actually shapes human-authored PRs.Today the live CI gate (
pr-issue-linkage) checks only a closing keyword plus a non-empty## Related, so nothing fails loudly — which is why this has gone unnoticed.Observed
Filing #3162 hit this directly: I mirrored the template (
Summary/Fix/Verification/Related) because that is the layout contributors see and the linkage gate keys onRelated. That PR merged green while not satisfying the configured section list.The decision to make
Which surface is authoritative:
pr_body_required_sectionstoSummary,Fix,Verification,Related. Keeps the richer human-facing structure;Verificationis arguably a better name thanTest planfor a repo whose PRs carry gate output.Summary,Test plan,Related. Closer to the plugin's portable default (Summary+Test plan), simpler for contributors.Option 1 preserves what the repo's PRs actually look like in practice. Either way the two should be edited together, and
docs/conventions/pr-body-convention/README.mdnotes a deferred CI consumer that would validate an already-opened body against the same key — worth settling this before that lands, or it will start failing PRs on a mismatch nobody chose.Related
docs/conventions/pr-body-convention/README.md— owner doc for the key.plugins/source-control/reference/config-resolution.md— resolution mechanics.